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.