5 ms·

Rdio: No REST for the wicked

52 points by garethr 16y ago

TillE 16y ago
our API, like most of the popular "REST" APIs, is not REST as defined by Roy Fielding Other APIs may be imperfect implementations of the ideal, but Rdio's made no attempt to look anything like REST. The complaint wasn't about adhering to a spec, but simply inaccurate nomenclature.
- tberman 16y ago
  How is it any more inaccurate than: http://www.flickr.com/services/api/request.rest.html http://www.flickr.com/services/api/request.rest.html
  - ianloic 16y ago
    Not to brag, but at least the Rdio API doesn't allow non-idempotent calls over GET.
  - garethr 16y ago
    It's not. But that doesn't make either of them right. I called Flickr on this 3 years ago before anyone actually visited my blog: http://morethanseven.net/2008/02/21/sorry-but-the-flickr-api-isnt-rest.html http://morethanseven.net/2008/02/21/sorry-but-the-flickr-api...
PaulHoule 16y ago
I like the term POX, except, like AJAX, that has an X that can be mistaken for "XML" although it can also be X for "Unknown". Unfortunately, the vernacular meaning of the word REST is "not SOAP".
- ianloic 16y ago
  Jens Alfke suggested PEST - Post Everything STyle: http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/comment-page-2/#comment-3962 http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/...
davidmathers 16y ago
When I started working on the Rdio API I struggled to work out how to effectively expose our API through a more classically REST model, but ultimately there was too much functionality that would be significantly more ugly when forced into a document-oriented REST model than exposed through an RPC model. Hi Ian, if it's not too much trouble could you give an example of functionality that didn't work well with REST?
- ianloic 16y ago
  Off the top of my head a couple of things that didn't map well were: * search * deleting songs from a playlist (safely) * multidimentional stats queries (eg: http://developer.rdio.com/docs/read/rest/Methods#getHeavyRotation http://developer.rdio.com/docs/read/rest/Methods#getHeavyRot...) Perhaps we could have modelled these in a REST-like manner, but it seemed simpler to make the functionality available through an RPC protocol - simpler for us to implement and simpler for developers to integrate into their software.
  - DougWebb 16y ago
    When I design RESTful APIs, I tyypically wind up with a collection resource for each of my resource types. (This is a common pattern, I think.) Searching and your getHeavyRotation are examples of "GET the collection resource, but filter the resources to include in the list". For this I use the path to identify the collection and query parameters to specify the filtering. Query parameters are appropriate here because they're not being used to specify which collection resource to retrieve. They're being used to alter the representation of the collection. This is just like using start and count query parameters to allow paging through a large collection. For your search, you would use a single query parameter, and for getHeavyRotation you would use one parameter for each field you can filter on. They'd be optional of course, and if none are specified you get the whole collection. Regarding deleting songs "safely", I'm not sure what you mean but I'm guessing you want some confirmation or recovery. I assume each song has a playlist attribute; instead of allowing a DELETE method on the song I would have a trashbin playlist, and allow the song resource to be updated with the playlist attribute changed to the trashbin uri. That allows the songs to be recovered if they are moved by mistake. To really clear it out, you could allow DELETE on /{trashbin uri}/{song id}. Eg: the song resource can only be deleted via the trashbin.
slackerIII 16y ago
If you are interested in music related APIs, my company (http://www.audiogalaxy.com http://www.audiogalaxy.com) has a draft API that lets you browse and play your music collection remotely. We support mp3, aac, flac, wma, vorbis, and get your playlists out of iTunes. We haven't publicized the API quite yet, but we would love get feedback from anybody who might be interested in it. Send me an email if you are: twk@audiogalaxy.com
ldh 16y ago
Kudos to the Rdio team for being responsive and thoughtful rather than defensive.
bromley 16y ago
I'm working on an RPC API that works with XML over HTTP. I'll be calling it an XML API. If it did JSON I'd call it a JSON API. Some customers seem to want to call it a REST API, but it would pain me to call it that when it isn't.
pbreit 16y ago
REST is totally useless since no one really knows wha it means and there are few if any APIs that come close to being "RESTful". REST's proponents, including Roy, have done a dreadful job educating on what REST is. As I commented on the Rdio thread, it would be nice if the complainers actually suggested how the API in question could be designed more RESTfully.

52 points by garethr 16y ago

TillE 16y ago

our API, like most of the popular "REST" APIs, is not REST as defined by Roy Fielding Other APIs may be imperfect implementations of the ideal, but Rdio's made no attempt to look anything like REST. The complaint wasn't about adhering to a spec, but simply inaccurate nomenclature.

tberman 16y ago
How is it any more inaccurate than: http://www.flickr.com/services/api/request.rest.html http://www.flickr.com/services/api/request.rest.html
- ianloic 16y ago
  Not to brag, but at least the Rdio API doesn't allow non-idempotent calls over GET.
- garethr 16y ago
  It's not. But that doesn't make either of them right. I called Flickr on this 3 years ago before anyone actually visited my blog: http://morethanseven.net/2008/02/21/sorry-but-the-flickr-api-isnt-rest.html http://morethanseven.net/2008/02/21/sorry-but-the-flickr-api...

PaulHoule 16y ago

I like the term POX, except, like AJAX, that has an X that can be mistaken for "XML" although it can also be X for "Unknown". Unfortunately, the vernacular meaning of the word REST is "not SOAP".

ianloic 16y ago
Jens Alfke suggested PEST - Post Everything STyle: http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/comment-page-2/#comment-3962 http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/...

davidmathers 16y ago

When I started working on the Rdio API I struggled to work out how to effectively expose our API through a more classically REST model, but ultimately there was too much functionality that would be significantly more ugly when forced into a document-oriented REST model than exposed through an RPC model. Hi Ian, if it's not too much trouble could you give an example of functionality that didn't work well with REST?

ianloic 16y ago
Off the top of my head a couple of things that didn't map well were: * search * deleting songs from a playlist (safely) * multidimentional stats queries (eg: http://developer.rdio.com/docs/read/rest/Methods#getHeavyRotation http://developer.rdio.com/docs/read/rest/Methods#getHeavyRot...) Perhaps we could have modelled these in a REST-like manner, but it seemed simpler to make the functionality available through an RPC protocol - simpler for us to implement and simpler for developers to integrate into their software.
- DougWebb 16y ago
  When I design RESTful APIs, I tyypically wind up with a collection resource for each of my resource types. (This is a common pattern, I think.) Searching and your getHeavyRotation are examples of "GET the collection resource, but filter the resources to include in the list". For this I use the path to identify the collection and query parameters to specify the filtering. Query parameters are appropriate here because they're not being used to specify which collection resource to retrieve. They're being used to alter the representation of the collection. This is just like using start and count query parameters to allow paging through a large collection. For your search, you would use a single query parameter, and for getHeavyRotation you would use one parameter for each field you can filter on. They'd be optional of course, and if none are specified you get the whole collection. Regarding deleting songs "safely", I'm not sure what you mean but I'm guessing you want some confirmation or recovery. I assume each song has a playlist attribute; instead of allowing a DELETE method on the song I would have a trashbin playlist, and allow the song resource to be updated with the playlist attribute changed to the trashbin uri. That allows the songs to be recovered if they are moved by mistake. To really clear it out, you could allow DELETE on /{trashbin uri}/{song id}. Eg: the song resource can only be deleted via the trashbin.

slackerIII 16y ago

If you are interested in music related APIs, my company (http://www.audiogalaxy.com http://www.audiogalaxy.com) has a draft API that lets you browse and play your music collection remotely. We support mp3, aac, flac, wma, vorbis, and get your playlists out of iTunes. We haven't publicized the API quite yet, but we would love get feedback from anybody who might be interested in it. Send me an email if you are: twk@audiogalaxy.com

ldh 16y ago

Kudos to the Rdio team for being responsive and thoughtful rather than defensive.

bromley 16y ago

I'm working on an RPC API that works with XML over HTTP. I'll be calling it an XML API. If it did JSON I'd call it a JSON API. Some customers seem to want to call it a REST API, but it would pain me to call it that when it isn't.

pbreit 16y ago

REST is totally useless since no one really knows wha it means and there are few if any APIs that come close to being "RESTful". REST's proponents, including Roy, have done a dreadful job educating on what REST is. As I commented on the Rdio thread, it would be nice if the complainers actually suggested how the API in question could be designed more RESTfully.