9 ms·

Dudes, this is so not REST

310 points by mccutchen 16y ago

mccutchen 16y ago
We might be getting close to this point: Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than “HTTP API that’s not as hard to use as SOAP”? This is a shame, because RESTful APIs are (for me, anyway) usually a joy to build and to use.
- mattmanser 16y ago
  Yes, though this one's especially bad for not even bothering to use different URLs.
- deno 16y ago
  There's already a specific term for the kind of API that rdio has: RPC. Remote Procedure Call. I mean, come on, how can you say you have REST (with R standing for Representational) if you have section called “Methods” in your API documentation. HTTP API sounds okay, but in fact their API is not even HTTP specific (actually, it abuses HTTP).
- masklinn 16y ago
  > We might be getting close to this point: Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than “HTTP API that’s not as hard to use as SOAP”? Well except RDIO's API is not any simpler to use than SOAP. It's RPC to and through, let's call a procedure call a procedure call.
hinathan 16y ago
Instead of fetishizing REST for its own sake, how about appreciating an HTTP API that can be used (read/written) with a browser via form elements and hrefs?
- deno 16y ago
  This can be done on top of REST API with your server acting as a client to your own API. Actually, that way it'll probably be possible to implement it much safer. And what's the use case anyway? Are you going to perform those requests from other domains and authenticating via cookies on your own? How do you protect from CSRF doing that? What's wrong with OAuth 2.0 + JS?
- figure8 16y ago
  I completely agree with you. There will always be a contingent of developers who believe enforced standards trump simplicity. As we see here, when the CORBA then SOAP crowd realized they'd lost that fight, their ilk started judging other projects by adherence to strict API structural definitions like formal "REST". That said, I do believe this constant dialog between ad-hoc simplicity and rigid standards is good for the industry; in each area, accepted practice evolves to meet the needs of its current application.
  - deno 16y ago
    REST is as simple as it gets. You could make that argument if someone were to advocate using REST outside of HTTP. But HTTP is inherently REST, so you should have a good reason to not use REST rather than the other way around.
    - masklinn 16y ago
      > REST is as simple as it gets. It is not. It's quite complex actually. And I'm betting what most people who believe they have a clue think of "REST" is actually "RPC over pretty urls".
      - deno 16y ago
        But that's just because of a general ignorance of how HTTP protocol works. If someone were to be explained, how it should work from the beginning, I'm sure they'd have no problem with grasping the subject. Actually some Google engineers do a very good job of explaining how AtomPub and GData APIs work just with short Youtube videos.
mortice 16y ago
I once worked on a project where 'REST' was synonymous with 'putting query data into the URL before the query string', and this was done so that the webserver could cache the response. I died a little inside every time I wrote a 'Restful' servlet there.
tariq 16y ago
how about calling it RESTish? http://news.ycombinator.com/item?id=2242162 http://news.ycombinator.com/item?id=2242162
- tptacek 16y ago
  It's not RESTish.
- masklinn 16y ago
  How about calling it what it is, namely RPC?
  - wahnfrieden 16y ago
    Yes. The terms "RESTish" or "lower REST" are just a way to stay buzzword compliant, not actually a way of elucidating anything. They're catch-all buzzword substitutes for more accurate terms. They're particularly bad since a strict interpretation of REST can still be valuable, yet it makes REST itself seem overly nebulous and fluffy. People advocating terms like "RESTish" or looser definitions of REST seem to think that REST is an ultimate goal of any decent web API. It's not, REST doesn't need to be used everywhere, your API isn't crap if it's not REST. So stop calling it REST like you're embarrassed to admit it's "just" RPC. (Sorry for ranting in reply to you -- you seem to get it)
- billybob 16y ago
  Or "drowsy?"
- tariq 16y ago
  lol whoops, forgot my sarcasm tags. i was not advocating calling anything RESTish.
mikeryan 16y ago
After reading the title I was all set to come in here and complain about "REST" Nazis and make some comment about how real life situations tend to supersede strict adherence to conventions. But then I read the article and I have to admit this is a pretty egregious break with how REST services are supposed to work.
- tptacek 16y ago
  I came here to say the same thing. For those of you who aren't going to bother reading the Rdio API spec (I did, because there's something I want to hack together with it): the whole API is literally just a single URI that accepts a "method" param, where the method is a list of verbs like "get all tracks in this playlist" or "add a friend". There's a case to be made for relaxing the definition of REST to accept "just a bunch of URIs" APIs that don't follow the discoverability/transparency conventions of REST. But you can't call "here's a list of verbs" a REST interface. What you'd want to see in a Rdio REST interface would be: * /rdio/api/1/playlists * /rdio/api/1/playlist/foo * /rdio/api/1/artist/1 * /rdio/api/1/artist/1/tracks/2 &c &c &c. But, from what I can tell, none of the state inside Rdio's database is mapped to a URI.
  - masklinn 16y ago
    > What you'd want to see in a Rdio REST interface would be: You should disclaim that these URLs could just as well be * /rdio?q=1&s=63 * /rdio?q=1&s=63-8 * /rdio/4E7?q=1 * /rdio/4E63?q=1 and still be part of a RESTful API.
    - swombat 16y ago
      No, those are not part of a REST API. You've got it wrong.
      - justincormack 16y ago
        Actually URLs are supposd to be opaque in rest so that is correct. Nice urls with http verbs but no hateos is what most "REST" APIs are though.
jcromartie 16y ago
Actually, what the blog author is talking about is a resource-oriented architecture (ROA), which is typically implemented in a RESTful fashion over HTTP but has recently been conflated with REST itself. ROA != REST.
- strmpnk 16y ago
  Exactly. ReST as a concept is not even tied to HTTP. HTTP's design was just heavily influenced my ReST so it happens to be good at it. Somehow people are obsessed over URL formatting and HTTP specificities... while they are important, it's not the literal embodiment of what representation state transfer is, just an implementation of it. What most people talk about when they say REST are good HTTP practices. Meaningful URLs, proper methods, etc... are all about using HTTP properly. We can call some of these views other acronyms like ROA but it's really just appreciation for proper and modern HTTP stacks.
  - masklinn 16y ago
    > HTTP's design was just heavily influenced my ReST so it happens to be good at it. REST was extracted from HTTP. It's not that HTTP was influenced by REST, it's the exact opposite, REST is a formalization of HTTP.
    - strmpnk 16y ago
      Actually, that's not true. ReST was developed in parallel with HTTP 1.1. It used the basics from HTTP 1.0 to express some of the new ideas. You can read about the original idea in Fielding's disertation here: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... If it were an extraction of anything, it wouldn't have been HTTP but existing ideas in scaling web architectures in general at the time.
- edw 16y ago
  Thank you for calling a spade a spade! The author talks about REST being object-oriented when it is actually resource-oriented. I know I'm flirting with pedantry for getting worked up about this, but anyone who knows what "object-oriented" actually means is either lying or ignorant of the manifold meanings associated with that term.
sabat 16y ago
It’s object-oriented, where objects are identified by URLs I'm not so sure that "object-oriented" is the right term here, but totally agree with the premise: this isn't REST. It's more like XML-RPC Jr.
vegashacker 16y ago
Why does it matter? Ok, I agree that you probably shouldn't label something with an incorrect term, but does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? I personally find that sometimes I have trouble spotting the "oh! I forgot to make it DELETE instead of GET" bugs. When the parameters of the API are all in the url and/or query, it feels better encapsulated. (promise I'm not flaming, and I fully expect to get told, yes it matters, and here's why! ;)
- tptacek 16y ago
  Yes. In this case, it makes an enormous difference. Your application can't just go to rdio/api/1/artist/whatever to look up the tracks for an artist; it has to make a SOAP-style request for the tracks for a given artist. This isn't a style nit.
  - vegashacker 16y ago
    In trying to prove you wrong and show you how easy it would be to make a similar call with the rdio API, I found out how not easy it would be to make a similar call with the rdio API. :)
  - masklinn 16y ago
    It can probably be argued to be: you can't just go to rdio/api/1/artist/whatever, but you can get the exact same thing via RPC calls. I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. Furthermore, just because an API is restful doesn't mean it's well-designed, and doesn't mean it has descriptive APIs (the artist's track could just as well be in rdio/api/64D89CAC?q=42, that wouldn't inherently make the API non-restful)
    - deno 16y ago
      > I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. It should be trivial with AtomPub/GData/OData APIs. REST itself is not specific enough for that.
csears 16y ago
REST is now just a generic term for any HTTP API that's not SOAP. Like Xerox and Kleenex, the popular usage is technically incorrect, but in practice, it doesn't matter. Most REST API consumers today are more like CURL than a web browser. In the CURL-like case, the RPC pattern works quite well. HATEOS and other browser-centric REST ideas often just don't fit naturally into a simple API consuming app. People need to move on.
- wycats 16y ago
  Except that there was already a perfectly good name for that: RPC. REST was defined in contrast to RPC, so calling an API that involves "POST to this URL with the method as a parameter" REST is really unnecessarily confusing.
- russellperry 16y ago
  "Like Xerox and Kleenex, the popular usage is technically incorrect, but in practice, it doesn't matter." The integrity of some acronyms is worth defending. I wouldn't want 'ACID' diluted to mean anything less than its strict definition, and I think the same holds true for 'REST'. The benefit of these distinctions is twofold: 1) we encourage the advantages of good RESTful practices and 2) we can communicate consistently without spending unnecessary effort qualifying our meaning. If REST means 'Anything but SOAP' then at some point we'll have to come up with another shorthand for 'Real REST' or spend lots of time re-stating the principles of REST every time we need to communicate architectural strategies that use them. I should be able to say 'Singleton' or 'MVC' or 'ACID' and know that there is enough integrity to those ideas that a competent coder will know what I mean without me having to pseudo-code or UML the concept for them. The same should hold true for REST.
- wycats 16y ago
  Except that there was already a perfectly good name for that: RPC. REST was defined in contrast to RPC, so calling an API that involves "POST to this URL with the method as a parameter" REST is really unnecessarily confusing.
- masklinn 16y ago
  > REST is now just a generic term for any HTTP API that's not SOAP. So you're telling me I should call my XML-RPC APIs REST?
deleted 16y ago
[deleted]
thurn 16y ago
This is an increasingly common extension of the REST paradigm. Google ran into a number of problems with the restrictions of REST, so their new APIs all work this way. See their justification in this video: http://www.google.com/events/io/2010/sessions/how-google-builds-apis.html http://www.google.com/events/io/2010/sessions/how-google-bui...
- br1 16y ago
  Note that there's also a pdf if you don't have the time for the whole video.
- deno 16y ago
  Those are not restrictions to REST, since REST doesn't make any specific claims about how to use things like filtering, sorting etc. Google created GData2 as an extension to AtomPub format, which only specifies a common envelope for resources (Atom Syndication Format) and how to talk about collections of resources (AtomPub itself). There is another notable extension to AtomPub format from Microsoft called OData.
- megrimlock 16y ago
  Slide 87 of the pdf has the best summary, but the main thing w/r/r REST is that get/put of entire resources can be too heavy. 1. custom methods let you get/put specific fields, without having to transfer the whole thing or split resources up as you add new methods. 2. custom methods avoid needing to implement complex or heavy state mutations on the client. the example was rotating an image 90 degrees; you wouldn't want to download an entire full-res image to your wimpy battery-powered phone, rotate it, and re-upload it when you can just do that on the server. (... of course this should just update some orientation metadata instead of resampling the image -- it's just an example)
  - _sh 16y ago
    As for your point 2, if you consider a REST resource as a collection of fields, you can update it without custom verbs: GET /resources/picture/orientation => 0 PUT /resources/picture/orientation?value=90 REST is not so much about a simple API, but a scalable service. Custom verbs break scalability.
adolph 16y ago
Summary: Rdo: "Yeah, we have POST!" Thought Palace: "What about the rest?"
extension 16y ago
This sort of API is not RESTful at all, regardless of whether the method name is in the HTTP header or a form variable. It's still an application-specific protocol that requires out-of-band knowledge to use. REST resources are supposed to be self-describing, which doesn't make much sense for an API like this. RPC is what is required here, so just tunnel RPC over HTTP in whatever way is most practical. And don't call it REST. If you want a bucket of cold water over the head on this topic: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
MatthewPhillips 16y ago
I've worked with APIs that return XML containing one node, which contains escaped XML. So when I read something like this it doesn't seem that bad.
- wahnfrieden 16y ago
  That's fine. Just don't call it REST. Does buzzword compliance matter so much? Call it what it is: RPC.
hoop 16y ago
'''Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than "HTTP API that’s not as hard to use as SOAP"?''' To be fair, I thought we were at this point already. It seems safer to assume that when one advertises a "RESTful API" they are really referring to a "REST-like" API which basically means "Hey, we don't use sessions!" While I believe that the term is already diluted to that point, I still think it's valid to point out when people are doing it wrong.
- wahnfrieden 16y ago
  It's diluted for sure, but it still carries a strict interpretation that is worthwhile and that some of us are still using. My main problem with its dilution is that it's usually totally meaningless -- usually other terms like RPC or just plain old "proper HTTP" accurately describe what someone is calling REST, to there point where its supposed RESTfulness can be nothing more than for the sake of buzzword compliance.
TorKlingberg 16y ago
I am all with you on using GET and POST properly, but is there any REST API that actually uses PUT and DELETE?
- wahnfrieden 16y ago
  Take a look at Sun Cloud API. It's one of the best examples. For APIs that need regular browser support, it's fine to add fallbacks like query params to specify PUT or DELETE. But these are hacks.
whackberry 16y ago
FTA > In fact this is why Tim Berners-Lee used the word “method” in the HTTP protocol in the first place. Does he have a source for this? Coincidentally I had just read the HTTP 0.9 the other day and I didn't see "method" being used that way at all. I think method, in HTTP, just means "a means to retrieve / put data", not method in the object oriented sense.
amitraman1 16y ago
Yes! Yes! Yes! "HTTP API that’s not as hard to use as SOAP" My current employer calls our API ... ... RESTful like .
davidmathers 16y ago
"It screams RPC. There is so much coupling on display that it should be given an X rating." -- Roy Fielding @ http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
mkramlich 16y ago
So it's an HTTP-based API rather than true REST. Move on. shrug
robbles 16y ago
The author gives WebDAV as an example of a good standardized REST API. Is adding new HTTP methods (like PROPFIND, MOVE, COPY, etc.) considered to be RESTful? I always thought you were supposed to structure all actions around the main 6, and add extra functionality in the data payload or query parameters.
thomasfl 16y ago
This is a good example of a REST anti pattern. It can be easier to understand REST, when you know what it's not.
Stormbringer 16y ago
In the Java world REST was pretty cool for about 18 months. And then annotations came out, and instead of all the JAX-RPC bondage and discipline, you get JAX-WS, where to make something a webservice literally all you need to do is shove the @WebService annotation on it and you are good to go†. All the WSDL and SOAP crap gets auto-generated for you. Thereby eliminating in a single stroke REST's advantage. Now, it is true that there is some stuff†† you can do with SOAP that you can't do with JAX-WS, but really unless you like making life difficult for yourself then don't. Especially for a big Java to Java solution there doesn't seem to be any compelling reason to go with REST anymore. Even if everything you do maps exactly to the four SQL ops (select, update, insert, delete) it is still just as easy to use the annotation as it would be to use REST. †C# has something similar I think. ††Example: JAX-WS is limited to what you can do with a method and parameters in Java. In your SOAP schema you can specify for instance that the array you get passed shall have between 1 and 3 members, two is okay but 4 is right out. Whereas in Java (and hence JAX-WS) if you have an Array parameter, you can't specify that it must have a certain number of elements in it.
- Ingaz 16y ago
  The simplest method of creating SOAP-services is use of SQLServer SOAP Endpoint. Just one line for SOAP from stored procedure or function. Is it beautiful? I don't think so. SOAP remains SOAP, ugly remains ugly.
ianloic 16y ago
Yep, our API isn't really technically REST in the classical use of the term. We changed some of our wording and made a blog post: http://developer.rdio.com/blog/read/No_REST_for_the_wicked http://developer.rdio.com/blog/read/No_REST_for_the_wicked

310 points by mccutchen 16y ago

We might be getting close to this point: Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than “HTTP API that’s not as hard to use as SOAP”? This is a shame, because RESTful APIs are (for me, anyway) usually a joy to build and to use.

mattmanser 16y ago
Yes, though this one's especially bad for not even bothering to use different URLs.
deno 16y ago
There's already a specific term for the kind of API that rdio has: RPC. Remote Procedure Call. I mean, come on, how can you say you have REST (with R standing for Representational) if you have section called “Methods” in your API documentation. HTTP API sounds okay, but in fact their API is not even HTTP specific (actually, it abuses HTTP).
masklinn 16y ago
> We might be getting close to this point: Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than “HTTP API that’s not as hard to use as SOAP”? Well except RDIO's API is not any simpler to use than SOAP. It's RPC to and through, let's call a procedure call a procedure call.

hinathan 16y ago

Instead of fetishizing REST for its own sake, how about appreciating an HTTP API that can be used (read/written) with a browser via form elements and hrefs?

deno 16y ago
This can be done on top of REST API with your server acting as a client to your own API. Actually, that way it'll probably be possible to implement it much safer. And what's the use case anyway? Are you going to perform those requests from other domains and authenticating via cookies on your own? How do you protect from CSRF doing that? What's wrong with OAuth 2.0 + JS?
figure8 16y ago
I completely agree with you. There will always be a contingent of developers who believe enforced standards trump simplicity. As we see here, when the CORBA then SOAP crowd realized they'd lost that fight, their ilk started judging other projects by adherence to strict API structural definitions like formal "REST". That said, I do believe this constant dialog between ad-hoc simplicity and rigid standards is good for the industry; in each area, accepted practice evolves to meet the needs of its current application.
- deno 16y ago
  REST is as simple as it gets. You could make that argument if someone were to advocate using REST outside of HTTP. But HTTP is inherently REST, so you should have a good reason to not use REST rather than the other way around.
  - masklinn 16y ago
    > REST is as simple as it gets. It is not. It's quite complex actually. And I'm betting what most people who believe they have a clue think of "REST" is actually "RPC over pretty urls".
    - deno 16y ago
      But that's just because of a general ignorance of how HTTP protocol works. If someone were to be explained, how it should work from the beginning, I'm sure they'd have no problem with grasping the subject. Actually some Google engineers do a very good job of explaining how AtomPub and GData APIs work just with short Youtube videos.

mortice 16y ago

I once worked on a project where 'REST' was synonymous with 'putting query data into the URL before the query string', and this was done so that the webserver could cache the response. I died a little inside every time I wrote a 'Restful' servlet there.

tariq 16y ago

how about calling it RESTish? http://news.ycombinator.com/item?id=2242162 http://news.ycombinator.com/item?id=2242162

tptacek 16y ago
It's not RESTish.
masklinn 16y ago
How about calling it what it is, namely RPC?
- wahnfrieden 16y ago
  Yes. The terms "RESTish" or "lower REST" are just a way to stay buzzword compliant, not actually a way of elucidating anything. They're catch-all buzzword substitutes for more accurate terms. They're particularly bad since a strict interpretation of REST can still be valuable, yet it makes REST itself seem overly nebulous and fluffy. People advocating terms like "RESTish" or looser definitions of REST seem to think that REST is an ultimate goal of any decent web API. It's not, REST doesn't need to be used everywhere, your API isn't crap if it's not REST. So stop calling it REST like you're embarrassed to admit it's "just" RPC. (Sorry for ranting in reply to you -- you seem to get it)
billybob 16y ago
Or "drowsy?"
tariq 16y ago
lol whoops, forgot my sarcasm tags. i was not advocating calling anything RESTish.

mikeryan 16y ago

After reading the title I was all set to come in here and complain about "REST" Nazis and make some comment about how real life situations tend to supersede strict adherence to conventions. But then I read the article and I have to admit this is a pretty egregious break with how REST services are supposed to work.

tptacek 16y ago
I came here to say the same thing. For those of you who aren't going to bother reading the Rdio API spec (I did, because there's something I want to hack together with it): the whole API is literally just a single URI that accepts a "method" param, where the method is a list of verbs like "get all tracks in this playlist" or "add a friend". There's a case to be made for relaxing the definition of REST to accept "just a bunch of URIs" APIs that don't follow the discoverability/transparency conventions of REST. But you can't call "here's a list of verbs" a REST interface. What you'd want to see in a Rdio REST interface would be: * /rdio/api/1/playlists * /rdio/api/1/playlist/foo * /rdio/api/1/artist/1 * /rdio/api/1/artist/1/tracks/2 &c &c &c. But, from what I can tell, none of the state inside Rdio's database is mapped to a URI.
- masklinn 16y ago
  > What you'd want to see in a Rdio REST interface would be: You should disclaim that these URLs could just as well be * /rdio?q=1&s=63 * /rdio?q=1&s=63-8 * /rdio/4E7?q=1 * /rdio/4E63?q=1 and still be part of a RESTful API.
  - swombat 16y ago
    No, those are not part of a REST API. You've got it wrong.
    - justincormack 16y ago
      Actually URLs are supposd to be opaque in rest so that is correct. Nice urls with http verbs but no hateos is what most "REST" APIs are though.

jcromartie 16y ago

Actually, what the blog author is talking about is a resource-oriented architecture (ROA), which is typically implemented in a RESTful fashion over HTTP but has recently been conflated with REST itself. ROA != REST.

strmpnk 16y ago
Exactly. ReST as a concept is not even tied to HTTP. HTTP's design was just heavily influenced my ReST so it happens to be good at it. Somehow people are obsessed over URL formatting and HTTP specificities... while they are important, it's not the literal embodiment of what representation state transfer is, just an implementation of it. What most people talk about when they say REST are good HTTP practices. Meaningful URLs, proper methods, etc... are all about using HTTP properly. We can call some of these views other acronyms like ROA but it's really just appreciation for proper and modern HTTP stacks.
- masklinn 16y ago
  > HTTP's design was just heavily influenced my ReST so it happens to be good at it. REST was extracted from HTTP. It's not that HTTP was influenced by REST, it's the exact opposite, REST is a formalization of HTTP.
  - strmpnk 16y ago
    Actually, that's not true. ReST was developed in parallel with HTTP 1.1. It used the basics from HTTP 1.0 to express some of the new ideas. You can read about the original idea in Fielding's disertation here: http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch... If it were an extraction of anything, it wouldn't have been HTTP but existing ideas in scaling web architectures in general at the time.
edw 16y ago
Thank you for calling a spade a spade! The author talks about REST being object-oriented when it is actually resource-oriented. I know I'm flirting with pedantry for getting worked up about this, but anyone who knows what "object-oriented" actually means is either lying or ignorant of the manifold meanings associated with that term.

sabat 16y ago

It’s object-oriented, where objects are identified by URLs I'm not so sure that "object-oriented" is the right term here, but totally agree with the premise: this isn't REST. It's more like XML-RPC Jr.

vegashacker 16y ago

Why does it matter? Ok, I agree that you probably shouldn't label something with an incorrect term, but does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? I personally find that sometimes I have trouble spotting the "oh! I forgot to make it DELETE instead of GET" bugs. When the parameters of the API are all in the url and/or query, it feels better encapsulated. (promise I'm not flaming, and I fully expect to get told, yes it matters, and here's why! ;)

tptacek 16y ago
Yes. In this case, it makes an enormous difference. Your application can't just go to rdio/api/1/artist/whatever to look up the tracks for an artist; it has to make a SOAP-style request for the tracks for a given artist. This isn't a style nit.
- vegashacker 16y ago
  In trying to prove you wrong and show you how easy it would be to make a similar call with the rdio API, I found out how not easy it would be to make a similar call with the rdio API. :)
- masklinn 16y ago
  It can probably be argued to be: you can't just go to rdio/api/1/artist/whatever, but you can get the exact same thing via RPC calls. I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. Furthermore, just because an API is restful doesn't mean it's well-designed, and doesn't mean it has descriptive APIs (the artist's track could just as well be in rdio/api/64D89CAC?q=42, that wouldn't inherently make the API non-restful)
  - deno 16y ago
    > I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. It should be trivial with AtomPub/GData/OData APIs. REST itself is not specific enough for that.

csears 16y ago

REST is now just a generic term for any HTTP API that's not SOAP. Like Xerox and Kleenex, the popular usage is technically incorrect, but in practice, it doesn't matter. Most REST API consumers today are more like CURL than a web browser. In the CURL-like case, the RPC pattern works quite well. HATEOS and other browser-centric REST ideas often just don't fit naturally into a simple API consuming app. People need to move on.

wycats 16y ago
Except that there was already a perfectly good name for that: RPC. REST was defined in contrast to RPC, so calling an API that involves "POST to this URL with the method as a parameter" REST is really unnecessarily confusing.
russellperry 16y ago
"Like Xerox and Kleenex, the popular usage is technically incorrect, but in practice, it doesn't matter." The integrity of some acronyms is worth defending. I wouldn't want 'ACID' diluted to mean anything less than its strict definition, and I think the same holds true for 'REST'. The benefit of these distinctions is twofold: 1) we encourage the advantages of good RESTful practices and 2) we can communicate consistently without spending unnecessary effort qualifying our meaning. If REST means 'Anything but SOAP' then at some point we'll have to come up with another shorthand for 'Real REST' or spend lots of time re-stating the principles of REST every time we need to communicate architectural strategies that use them. I should be able to say 'Singleton' or 'MVC' or 'ACID' and know that there is enough integrity to those ideas that a competent coder will know what I mean without me having to pseudo-code or UML the concept for them. The same should hold true for REST.
wycats 16y ago
Except that there was already a perfectly good name for that: RPC. REST was defined in contrast to RPC, so calling an API that involves "POST to this URL with the method as a parameter" REST is really unnecessarily confusing.
masklinn 16y ago
> REST is now just a generic term for any HTTP API that's not SOAP. So you're telling me I should call my XML-RPC APIs REST?

deleted 16y ago

[deleted]

thurn 16y ago

This is an increasingly common extension of the REST paradigm. Google ran into a number of problems with the restrictions of REST, so their new APIs all work this way. See their justification in this video: http://www.google.com/events/io/2010/sessions/how-google-builds-apis.html http://www.google.com/events/io/2010/sessions/how-google-bui...

br1 16y ago
Note that there's also a pdf if you don't have the time for the whole video.
deno 16y ago
Those are not restrictions to REST, since REST doesn't make any specific claims about how to use things like filtering, sorting etc. Google created GData2 as an extension to AtomPub format, which only specifies a common envelope for resources (Atom Syndication Format) and how to talk about collections of resources (AtomPub itself). There is another notable extension to AtomPub format from Microsoft called OData.
megrimlock 16y ago
Slide 87 of the pdf has the best summary, but the main thing w/r/r REST is that get/put of entire resources can be too heavy. 1. custom methods let you get/put specific fields, without having to transfer the whole thing or split resources up as you add new methods. 2. custom methods avoid needing to implement complex or heavy state mutations on the client. the example was rotating an image 90 degrees; you wouldn't want to download an entire full-res image to your wimpy battery-powered phone, rotate it, and re-upload it when you can just do that on the server. (... of course this should just update some orientation metadata instead of resampling the image -- it's just an example)
- _sh 16y ago
  As for your point 2, if you consider a REST resource as a collection of fields, you can update it without custom verbs: GET /resources/picture/orientation => 0 PUT /resources/picture/orientation?value=90 REST is not so much about a simple API, but a scalable service. Custom verbs break scalability.

adolph 16y ago

Summary: Rdo: "Yeah, we have POST!" Thought Palace: "What about the rest?"

extension 16y ago

This sort of API is not RESTful at all, regardless of whether the method name is in the HTTP header or a form variable. It's still an application-specific protocol that requires out-of-band knowledge to use. REST resources are supposed to be self-describing, which doesn't make much sense for an API like this. RPC is what is required here, so just tunnel RPC over HTTP in whatever way is most practical. And don't call it REST. If you want a bucket of cold water over the head on this topic: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

MatthewPhillips 16y ago

I've worked with APIs that return XML containing one node, which contains escaped XML. So when I read something like this it doesn't seem that bad.

wahnfrieden 16y ago
That's fine. Just don't call it REST. Does buzzword compliance matter so much? Call it what it is: RPC.

hoop 16y ago

'''Maybe we should just give up on the term REST, since it’s become so diluted as to mean nothing more than "HTTP API that’s not as hard to use as SOAP"?''' To be fair, I thought we were at this point already. It seems safer to assume that when one advertises a "RESTful API" they are really referring to a "REST-like" API which basically means "Hey, we don't use sessions!" While I believe that the term is already diluted to that point, I still think it's valid to point out when people are doing it wrong.

wahnfrieden 16y ago
It's diluted for sure, but it still carries a strict interpretation that is worthwhile and that some of us are still using. My main problem with its dilution is that it's usually totally meaningless -- usually other terms like RPC or just plain old "proper HTTP" accurately describe what someone is calling REST, to there point where its supposed RESTfulness can be nothing more than for the sake of buzzword compliance.

TorKlingberg 16y ago

I am all with you on using GET and POST properly, but is there any REST API that actually uses PUT and DELETE?

wahnfrieden 16y ago
Take a look at Sun Cloud API. It's one of the best examples. For APIs that need regular browser support, it's fine to add fallbacks like query params to specify PUT or DELETE. But these are hacks.

whackberry 16y ago

FTA > In fact this is why Tim Berners-Lee used the word “method” in the HTTP protocol in the first place. Does he have a source for this? Coincidentally I had just read the HTTP 0.9 the other day and I didn't see "method" being used that way at all. I think method, in HTTP, just means "a means to retrieve / put data", not method in the object oriented sense.

amitraman1 16y ago

Yes! Yes! Yes! "HTTP API that’s not as hard to use as SOAP" My current employer calls our API ... ... RESTful like .

davidmathers 16y ago

"It screams RPC. There is so much coupling on display that it should be given an X rating." -- Roy Fielding @ http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...

mkramlich 16y ago

So it's an HTTP-based API rather than true REST. Move on. shrug

robbles 16y ago

The author gives WebDAV as an example of a good standardized REST API. Is adding new HTTP methods (like PROPFIND, MOVE, COPY, etc.) considered to be RESTful? I always thought you were supposed to structure all actions around the main 6, and add extra functionality in the data payload or query parameters.

thomasfl 16y ago

This is a good example of a REST anti pattern. It can be easier to understand REST, when you know what it's not.

Stormbringer 16y ago

In the Java world REST was pretty cool for about 18 months. And then annotations came out, and instead of all the JAX-RPC bondage and discipline, you get JAX-WS, where to make something a webservice literally all you need to do is shove the @WebService annotation on it and you are good to go†. All the WSDL and SOAP crap gets auto-generated for you. Thereby eliminating in a single stroke REST's advantage. Now, it is true that there is some stuff†† you can do with SOAP that you can't do with JAX-WS, but really unless you like making life difficult for yourself then don't. Especially for a big Java to Java solution there doesn't seem to be any compelling reason to go with REST anymore. Even if everything you do maps exactly to the four SQL ops (select, update, insert, delete) it is still just as easy to use the annotation as it would be to use REST. †C# has something similar I think. ††Example: JAX-WS is limited to what you can do with a method and parameters in Java. In your SOAP schema you can specify for instance that the array you get passed shall have between 1 and 3 members, two is okay but 4 is right out. Whereas in Java (and hence JAX-WS) if you have an Array parameter, you can't specify that it must have a certain number of elements in it.

Ingaz 16y ago
The simplest method of creating SOAP-services is use of SQLServer SOAP Endpoint. Just one line for SOAP from stored procedure or function. Is it beautiful? I don't think so. SOAP remains SOAP, ugly remains ugly.

ianloic 16y ago

Yep, our API isn't really technically REST in the classical use of the term. We changed some of our wording and made a blog post: http://developer.rdio.com/blog/read/No_REST_for_the_wicked http://developer.rdio.com/blog/read/No_REST_for_the_wicked