

Rdio: No REST for the wicked - garethr
http://developer.rdio.com/blog/read/No_REST_for_the_wicked

======
TillE
_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
How is it any more inaccurate than:
<http://www.flickr.com/services/api/request.rest.html>

~~~
ianloic
Not to brag, but at least the Rdio API doesn't allow non-idempotent calls over
GET.

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

------
davidmathers
_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
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#getHeavyRot...](http://developer.rdio.com/docs/read/rest/Methods#getHeavyRotation))

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
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.

~~~
tberman
Given then, how would you map a search that returns multiple types?

As far as deleting songs "safely", what Ian means is that for any given
playlist (of which a user has an unlimited number) any given song can be in it
any number of times. So when you delete a song, we generally ask for song_id
and index to make sure that a) the playlist hasn't mutated (much), and b) we
are dropping the right song. The DELETE on /{trashbin uri}/{song id} doesn't
provide 2 of the 3 required bits of information, and DELETE
/playlist/{playlist id}/{song id}/{index} isn't very RESTful (imo).

~~~
davidmathers
_DELETE /playlist/{playlist id}/{song id}/{index} isn't very RESTful (imo)_

Your opinion is a fact, imo. Songs can't be deleted from playlists using REST,
full stop. Songs-in-playlists are values, not identities, so they can't be
resources. I see it as analogue to words in a text file. A REST client would
have to construct the updated playlist value and PUT the whole thing to the
playlist resource. So "delete song from playlist" is a function that could
only exist in the client.

Search on the other hand is just search. I don't think REST vs RPC has much to
say about it. The only issue would be location: URL vs method.

~~~
generalk
> Your opinion is a fact, imo

This doesn't parse very well to me.

As far as your main point, I disagree. The
/playlist/:playlist_id/:song_id/:index thing doesn't seem very good, no. But,
if you kept an id that mapped songs to playlists, you could easily do DELETE
/playlists/:playlist_id/:song_playlist_id and be done with it.

REST doesn't say you have to update the entire resource just because a member
of that resource needs to be deleted.

~~~
davidmathers
I agree with you hypothetically. But my question was about their real world
issues.

They could, _in theory_ , have ids for songs-in-playlists. But they don't in
fact have them and their RPC api doesn't require them. That's what I'm
interested in. Not how they could change their architecture to make REST work.

~~~
AffableSpatula
if it's a big deal to make that change then their underlying architecture
needs a review.

------
bromley
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.

------
slackerIII
If you are interested in music related APIs, my company
(<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

------
pbreit
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.

------
PaulHoule
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
Jens Alfke suggested PEST - Post Everything STyle:
[http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-
rest/...](http://jens.mooseyard.com/2011/03/dudes-this-is-so-not-rest/comment-
page-2/#comment-3962)

