DEV Community

loading...

Discussion on: API Sorrows

Collapse
wulymammoth profile image
David • Edited

Thoroughly enjoyed your rant, Adam. LOL.

I work on designing APIs from time to time and funnily enough, I've worked on two hackathon apps that use Spotify's API.

But for anyone that's worked with anything in software long enough, we can always invoke the "law of leaky abstractions" -- in this context, though, this basically amounts to someone (API designers/architects) making assumptions (which we all must sort of do), because there's no possible way to enumerate all the possible ways that end-users will consume an API's resources.

Let's revisit your operations on the playlist resource (from Spotify) -- with the limit being 100 tracks. I still think this is fair, because there may be an internal metric that shows that most playlists, save for the largely curated and disseminated ones (but even many of those) contain less than 100 tracks. I think your use case is more an exceptional one rather than the most common. Letting a few consumers do as you're doing (multiple requests) -- is actually okay. But I will admit, it could be an oversight as a sane default. One of the toy apps that I worked on, operated on playlists, but only removal and appending of tracks and its metadata, like name, description, # of tracks. I would imagine that there may be some underlying reason, perhaps data model related, that makes 100 the default...

My thoughts with regard to REST -- I'm pretty pedantic and prefer some deterministic rules versus bending and opening up the window for exceptions, but what you've cited is just poor API design (if it forces consumers to use it in an inefficient manner), as REST doesn't necessarily dictate that. I've worked with a bunch of different specs and a lack of specs, but designed with flexibility in mind -- from the API provider's perspective, they'd like to reduce size of payload sent over the wire and not send any unnecessary data (could introduce multiple subroutines) -- one way that I've deal with this in the past is to allow an option for eager-loading associations/relations with an includes query parameter against the resource's endpoint. Alternatively, in today's world, GraphQL putting the onus on the consumer to specify precisely what they need, seems to be a considerable advantage here.

Lastly, I'll note that a hand-rolled API introduction and overview should also be requisite, because to my knowledge, back-porting Swagger for existing APIs won't generate enough documentation necessary for people to understand what a resource is even if we can read all the fields. It's necessary to discuss authentication, rate limits, elevated provisions (if any) or roles, and which resources are accessible at what access levels. Designing public APIs are hard.

But if it brings you any comfort, I, too, use to rant about the same things until someone asked me these questions or made at least think about what a designer/architect was thinking at the time that didn't seem too outside the lines.

Collapse
bytebodger profile image
Adam Nathaniel Davis Author

Love the feedback!

because there's no possible way to enumerate all the possible ways that end-users will consume an API's resources

Absolutely. Many of my rants originate from the fact that I'm forced to deal with the assumptions, made by others, about how I'll use the system. Of course, as a developer myself, I know that it's absolutely necessary to make assumptions. It can't be avoided. But I strongly believe that it's always a good idea to double- and triple-check those assumptions. Because ill-informed assumptions can make life hell for your end-users.

I think your use case is more an exceptional one rather than the most common.

This is an interesting point. On one hand, my (admittedly, anecdotal) experience is that most playlists do not contain fewer than 100 tracks. Because most of the people I've talked to about the headaches they have with Spotify are curating large playlists. Specifically, I've done a lot of tinkering with their broken shuffle functionality.

But I may be in my own demographic here. You see, if you're the type of person who's deeply concerned about your playlists' shuffle capabilities, then you probably have this concern because you have a large playlist. If your playlist contains, say, 30 tracks, then you may not care so much about which order they come up in.

I can confirm that there are a great many people who are deeply frustrated by Spotify's broken shuffle feature. But even that large population is probably a minority of Spotify's userbase. And for the majority of Spotify's userbase, their playlists may all be under 100 tracks.

one way that I've deal with this in the past is to allow an option for eager-loading associations/relations with an includes query parameter against the resource's endpoint. Alternatively, in today's world, GraphQL putting the onus on the consumer to specify precisely what they need, seems to be a considerable advantage here.

100% agree. From my perspective, you can make your API restrictive as hell - as long as you give the occasional consumer the ability to tailor the response. I'm fine with the idea that certain stuff doesn't come back by default. But it's frustrating when the only solution is for me to load up a series of successive API calls to get the "full" data set.

Collapse
wulymammoth profile image
David

But I may be in my own demographic here. You see, if you're the type of person who's deeply concerned about your playlists' shuffle capabilities, then you probably have this concern because you have a large playlist. If your playlist contains, say, 30 tracks, then you may not care so much about which order they come up in.

Fair! I do think there should be a forum or some way to voice such concerns through a developer advocate at the company. One thing that I really wanted, which Spotify likely won't give is track play count. It's been an issue filed against their API repo on GitHub that I chimed in on. Now, I'm wondering if your issue has been raised there, too. The "issue" associated with play count did receive responses from the Spotify team. I'm not a fan of these walled-gardens, especially as a paying customer. But going back to your issue, the onus is now put on you to write and maintain code to do extra work -- orchestrating multiple calls: essentially a reduce or concatenation and think about failure scenarios (if at scale) like what happens if 1/3 calls for an entire playlist fails? Nobody wants to write extra code when they don't need to....

It was only yesterday that I tweeted at Spotify and their SpotifyCares accounts about playlist management in the desktop application -- I can access the search bar with keyboard shortcut, but it doesn't expose search against my own playlists or my playlists for that matter. I was pretty frustrated and the work-around, having discovered on my own, was to create a folder and order the playlists that I always want immediate access to there as a way to "pin" it.

Thread Thread
bytebodger profile image
Adam Nathaniel Davis Author • Edited

Now, I'm wondering if your issue has been raised there, too.

FWIW, my issue has absolutely been brought up in their forum. And on their SpotifyCares accounts. The "answers" they give are... dismissive and insulting. (I reference this in the previous post, where I provide a link to one of my forum posts.) There are many forum threads started for this issue. Some of them go on for hundreds of pages. For the most part, Spotify ignores them or just provides a link to their 8-year-old blog article explaining their brilliant methodology. Far worse (IMHO), they've taken to simply marking the issues as "not an issue" or "implemented".

If you tell me, "We hear you, but it's not on our agenda to address this right now." I can actually deal with that. I get it. When you mark my issue as "not an issue" or "implemented" - after you've done nothing to address the issue, admittedly, it pisses me off.

I've actually come to realize that this is a standard feature of Spotify's "support". Even if you find something that's outright broken, good luck getting them to fix it. Or even to acknowledge it.

For another example of this, you used to be able to drag tracks from your History tab onto your playlists. Then, a few years ago, it just stopped working. No answer for why it doesn't work. It just doesn't. You can find references to it in the forums - but there is no fix action, nor any acknowledgment of the issue. One day it used to work. The next day it didn't. And if you don't like it... oh, well.

Thread Thread
bytebodger profile image
Adam Nathaniel Davis Author

I can access the search bar with keyboard shortcut, but it doesn't expose search against my own playlists or my playlists for that matter.

Interesting finding. I might add it to my Spotify Toolz site (spotifytoolz.com). I'm in the process of building it right now, but the first feature (basic, random shuffling) is live. I'm currently working on putting up de-dup capabilities, because I often find that I've managed to get multiple copies of some tracks in my playlists and Spotify doesn't really have any efficient way to deal with that. The site will also have an improved mechanism for finding new music (cuz their track suggestions are another one of my gripes that could fill an entire blog...).

I might add a search-in-playlists feature. I could see that as being helpful.

Forem Open with the Forem app