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! ;)
Yes. You can use libraries when the service you're trying to interact with works according to some standard.
An example: I have an app I wrote at work that is a JavaScript frontend powered by a REST API backend. The REST API tries to be a good REST citizen: proper HTTP implementation (201 + Location when something is created, 202 for "I will get to that eventually", etc.), consistent URL conventions, and a consistent data format.
The end result is an API that is easy for humans to understand, but also easy for computers to understand: the simple CRUD code was about 10 lines of backbone.js, because my API doesn't break any conventions. This means that the code to interact with it already exists, and all I had to do was make the web page look pretty.
This is a good use of programmer resources, now and in the future. In the present, I didn't have to do any work to make a pretty GUI. In the future, someone that wants to pull data from my API will not have to swear at me -- everything you can do is easily discoverable by starting from the root resource.
Note: Requiring that the call are OAuth'ed, doesn't affect its RESTness.
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)
What REST brings to table is exchanging representations. For one thing, it makes your API actually simpler, since you don't even need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should come natural if you know HTTP.
The other nice thing that you get for free is that it accommodates for unreliable connectivity. In case of failure you can just retry. OTOH RPC abstracts such things away. For example if you have a call like "addSomethingToList" and you retry that method, you risk having duplicates.
Pedantry: because they're supposed to be idempotent, POST, PUT, and DELETE should only have side-effects the first time they're issued against a given resource.
Also, RFC 2616 uses "SHOULD NOT", as opposed to "MUST NOT" to describe the behavior of the "safe methods". To wit, "in particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval."
Except those are of course guidelines, the API implementor is free to entirely disregard them (much to the danger of everybody)
> For one thing, it makes your API actually simpler, since you don't actually need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should be natural if you know HTTP.
Instead of a list of methods, you get a list of methods (which do not have to stay the same, by the way) and a tree of resources. Theoretically you should be able to crawl a REST API using only the document types and the root URL, I don't think I've ever seen a "public" API letting me that.
> OTOH RPC abstract such things away. For example if you have call like "addSomethingToList" and you retry that method you risk having duplicates.
Yes, because if you POST the same thing twice you don't risk fucking things up...
Oh you should be using PUT, not POST, you say? Good luck getting that one in browsers.
If you're expecting a REST API yes. It also significantly impairs the discovery and the cacheability of the API calls.
The crowd that mistakes ROA for REST (I think) sees the stuff in REST that relates directly to development and gets excited - but the stuff related to making their app scale, they ignore. If you don't want to learn a little bit about everything, at least follow the rules that relate to the things you don't know about.
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.
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.
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)
GET /resources/picture/orientation => 0
PUT /resources/picture/orientation?value=90
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.
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)
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.
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.
It implies that a resource is different just because you are using a newer version of the API.
My own most recent implementations use Accept: and Content-Type to define version compatibility, which is what content negotiation is supposed to be about.
Versioning in the old web API sense meant changing the way the protocol works, and REST will always be REST and the resources will always be resources.
All that is likely to change between 'API versions' is formats, which you negotiate with headers, and adding new fields, which old clients can either ask not to get through content negotiation or can safely ignore.
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.
http://www.youtube.com/watch?v=Sv5woNs9WRE
Being accurate with a technical term is not a 'fetish.'
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?
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.
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.
So you're telling me I should call my XML-RPC APIs REST?
This is a shame, because RESTful APIs are (for me, anyway) usually a joy to build and to use.
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).
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.
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.
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.
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.
Just one line for SOAP from stored procedure or function.
Is it beautiful? I don't think so. SOAP remains SOAP, ugly remains ugly.
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.
I died a little inside every time I wrote a 'Restful' servlet there.
-- Roy Fielding @ http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
If you want a bucket of cold water over the head on this topic: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
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.
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.
Rdo: "Yeah, we have POST!"
Thought Palace: "What about the rest?"
"HTTP API that’s not as hard to use as SOAP"
My current employer calls our API ...
... RESTful like .
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.