iTunes Search API: the epitome of bad API design
Recently, I’ve been working on several projects that have required a proper way to fetch album covers. After hearing about iTunes having a public API, I thought: “Oh this is great! The world’s biggest music library, a GET request away. And made by some of the world’s greatest programmers!”
Boy, was I wrong. Let’s get started with random complaints in no particular order.
GET parameters… They’re everywhere!
The whole API is manipulated through GET parameters. While configurability is good, the amount of parameters you have to use to get a simple set of results is flat-out overwhelming and a pain to understand properly.
Just take a look at the table in the documentation (can’t fit it here, it’s too long. You’ll understand. https://affiliate.itunes.apple.com/resources/documentation/itunes-store-web-service-search-api/
Mix, song, musicTrack, what?
The API uses entities for retrieval of information. This is great in well-designed APIs, for sorting your results accordingly. Well, unfortunately, the iTunes API developers decided to make a total clusterfuck of entity options.
Take musicTrack for an example. You, having heard the term used countless times and knowing its definition well, would think it means song. Turns out there is another entity called song, and musicTrack actually returns songs + musicVideo for the song. What? Oh, and we’re not done yet. Tracks nor song include mixes. If I even knew what a mix meant, because the docs don’t explain it. It could mean remixes, playlists, etc. I don’t know, frankly.
Naming conventions? Nobody uses naming conventions. Let’s make the API completely unpredictable!
Oh, boy.
As you can notice here, there’s various entities which mean basically the same thing, but some are prefixed and others not. There’s musicTrack, which covers song, and musicVideo. There’s musicArtist, then there’s shit like album.
Completely predictable and well designed.
Some options are way too broad or flat out unexplained
Let’s begin with software. We have software, with no explanation whatsoever on what it does. We can assume it means all software, but it’s just flat out vague. There’s iPadSoftware, which has no explanation on whether it covers all iOS software or just iPad, taking in consideration that iOSSoftware nor iPhoneSoftware isn’t in the list.
Then we have all. There’s a lot here to think about (naming conventions, grr) but I’ll stick to broadness. Let’s take a look at audiobook. Shouldn’t that be in a separate section called books, including ebook and audiobook?
wrapperType and kind are two different things
I feel like wrapperType needs a whole section for itself. Let’s say you’re asking for a small set of results: songs, albums, and artists. Good luck determining which type of result you received.
Here are all the cases I’ve had since I started dealing with, trying to tell if something is a song or album:
- Sometimes it randomly returns both wrapperType and kind.
- Sometimes, if you’re lucky, kind is returned, equaling song.
- Most of the time kind isn’t returned at all.
- Sometimes the API returns wrapperType == song.
- Sometimes, wrapperType is not returned, neither is kind.
- Sometimes it returns collectionName, which means it’s an album, or a song in an album.
- Sometimes wrapperType == album.
I could go on all day, seriously. With this API, the possibilities are truly endless. You will be forced to write shitty boilerplate code like this to prevent your app from exploding like a hydrogen bomb.
Artwork URLs are specific sizes
This isn’t really a big complaint in itself, just a nitpick. If you want full-size, HD album art, you have to resort to ugly hacks like what I did in my Python library.
Concluding
The iTunes API is bad.
Situations like this usually indicate a bigger problem, like bad internal engineering. This applies (especially) to old codebases like iTunes where the rot has started to seep in long ago, with feature bloat and abandonment. And it’s no secret their codebase is not very nice (this is pure speculation); the API is usually a direct reflection of how a codebase is designed, considering the API is built around a database and is (again, I’m just speculating here) a mirror of the database. I’d love to get some input from Apple engineers on this, however.
And I’m writing about this situation, hopefully to be heard. Making an open letter/request to Apple engineers to please improve your APIs. Or, if you’re too busy for that, at least document them properly. Please, for all our sakes.
This concludes my first (and hopefully not my last) article on Medium about programming! Any input on the article is very welcome, as long as you keep it civil. You can find me on GitHub, HN, and Twitter.
