REST
There have been a couple of things I've been linked to recently about how some APIs claim that they are RESTian, but aren't really - Gareth and Jens. To my mind, there's not a lot of clarity here. So.
Things that make your web service RESTian:
- Resources are represented by URLs.
- Resources can be cached according to their caching headers.
- You perform operations on those things using HTTP verbs (GET, DELETE, PUT, etc).
- You discover other resource URLs by examining other resources - for instance GETting the
/books/
resource might return a document that contains the URLs of all the books. - You can request a representation of a resource in different formats using the Accept header.
- Your API is stateless. (Presumably allowing for things like rate-limiting, of course)
Things that mean your API is NOT RESTian
- Your documentation describes how to construct URLs based on object IDs (
/books/{id}
) and is the only way of finding these URLs - Your API has a single endpoint and you pass the method as another parameter.
- HTTP verb use is restricted to just POST, or POST and GET.
Things that have no bearing on the RESTiness of your API:
- Your APIs look meaningful (like
/books/{id}
). - You return JSON. Or XML. Or anything in particular.
- You use the word REST in the documentation a lot.
Things that aren't magically true just because your API is RESTian:
- Writing clients is easy.
- You don't even need a client, you can just derive everything from a single endpoint.
- Your API maps properly onto your business objects and therefore makes sense.
- Your API will scale properly.
- Your API is easy to extend
- You won't get support requests from people who didn't read the documentation.
Hopefully this should help things a little.
If you disagree with anything above, mail me, I'm genuinely interested if I've misunderstood something here.
I also have my own opinions on REST vs non-REST. But I'm trying to be factual here.