CODEWITHSUNDEEP
apirestrestful-architecture
Flukey
Flukey

Reputation: 6555

A few questions about RESTful APIs and why some of the best-practices are rarely implemented

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:

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?

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.

Upvotes: 3

Views: 248

Answers (2)

Kevin Junghans
Kevin Junghans

Reputation: 17540

The true definition of REST is obviously in the doctoral dissertation written by Roy Fielding in 2002. Do all of the API's out there that call themselves RESTful follow the guidelines specified by Fielding? The answer is no. The definition of REST has been watered down by some to just mean anything that does not use SOAP. I would worry less about what is RESTful and more about what is good practices. It is a good practice to specify the content type in the header of the request. It is also a good practice to version your API's. A good resource for information on API best practices is from the guys at Apigee as they have a lot of experience in this area. Check out their webinar on RESTful API Design where they ask if you are a pragmatist or a RESTafarian.

Upvotes: 1

Darrel Miller
Darrel Miller

Reputation: 142222

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.

Upvotes: 5

Related Questions