Question

In most tutorials, documentation, articles etc. about RESTful I come across a few of the same points, but yet I rarely ever see these ‘What makes it RESTful’ points implemented.

For example, I’ve read this many times:

• Content type

  Using HTTP headers

  Accept: application/json, text/plain 
  

  Extension in the URL

  Not RESTful, URLs are not the place for Content-Type
  

I have never come across an API where I have seen this implemented. Every API I have ever used has always required me to append XML or JSON to the end of the URL. Are they doing it wrong?

• Versioning

  Version media types

  application/vnd.something.v1+json

  Custom header

  X-API-Version: 1

  Version in URL

  /v1/resouce
  Not RESTful, by putting the version in the URL you create separate resources

If you need to introduce non-backwards-compatible functionality surely creating a seperate resource is the correct thing to do?

Once again, in all versions of APIs I’ve used, they use v1, v2 in the URL (such as google, imgur etc.)

By not implementing these points, would my API not be considered RESTful?

To clarify these points would be much appreciated.

Answer 1

1) Using accept header or using format specific URLs are both valid in a RESTful system. The article you are citing is wrong.

2) Saying v1/resource is not RESTful is also incorrect. You cannot look at a URI and make a conclusion about its RESTfulness. Adding a v1 at the root of your URL is probably not a great thing to do if you are trying to incremental evolve your system. In effect it declares a whole new URL space and obsoletes the old one. That’s pretty drastic. RESTFul systems try and enable incremental and evolutionary change to a system. So doing /resource/v2 is actually much more compatible with that goal.

The unfortunate phenomena at work here is that many developers who are learning about REST discover that the vast majority of systems out there that claim to be doing REST are not actually conforming to the constraints of REST. So they quickly develop a zeal for telling everyone what is and is not RESTful. Many of these people have not yet fully understood the constraints and end up making up new ones that don’t exist. The “RESTFul URL” fallacy is a classic. “POST must create a resource” is another common one.

My guidance to anyone learning REST is, if someone tells you that something is not RESTful, you ask them what constraint it is violating and what is the practical impact of ignoring that constraint. If they can’t answer that, then politely ignore them.