What should the standard be for ReSTful URLS?

Question

Since I can't find a chuffing job, I've been reading up on ReST and creating web services. The way I've interpreted it, the future is all about creating a web service for all your data before you build the web app. Which seems like a good idea.

However, there seems to be a lot of contradictory thoughts on what the best scheme is for ReSTful URLs.

Some people advocate simple pretty urls

http://api.myapp.com/resource/1

In addition, some people like to add the API version to the url like so

http://api.myapp.com/v1/resource/1

And to make things even more confusing, some people advocate adding the content-type to get requests

http://api.myapp.com/v1/resource/1.xml
http://api.myapp.com/v1/resource/1.json
http://api.myapp.com/v1/resource/1.txt

Whereas others think the content-type should be sent in the HTTP header.

Soooooooo.... That's a lot of variation, which has left me unsure of what the best URL scheme is. I personally see the merits of the most comprehensive URL that includes a version number, resource locator and content-type, but I'm new to this so I could be wrong.

On the other hand, you could argue that you should do "whatever works best for you". But that doesn't really fit with the ReST mentality as far as I can tell since the aim is to have a standard.

And since a lot of you people will have more experience than me with ReST, I thought I'd ask for some guidance. So, with all that in mind...

What should the standard be for ReSTful URLS?

Answer 1

Welcome to the confusing world of what is and what is not REST. First I would suggest that you have been reading about REST in the wrong places. Try RESTWiki as a good starting point.

REST is not a great solution for delivering data services for your web app. "Web Services" (aka SOAP, XML-RPC, WSDL, HTTP-POX) may be good for that but the REST architectural style is much more oriented towards client-server scenarios than server-server scenarios.

Stop thinking about what URLs look like. What they look like has much more to do with which server side framework you use to implement the RESTful service than the design of the service itself. The client should discover URLs from previously retrieved representations, so it really does not care what the URLs look like.

Having said that, using your example URLs to try and distinguish what you believe should be different resources, I do have some other suggestions.

Don't version resources. i.e. if you have a resource that is accessed by the url http://example.org/TodaysWeather don't ever create a resource at http://example.org/V2/TodaysWeather. There are lots of other better ways to version representations than creating a whole new resource. Search SO for lots of other discussions on this.

As for creating different resources for different content-types, I believe that is a context specific decision. If your end-user is using a browser to access the REST service and they are sophisticated enough to understand the difference between JSON and XML then go ahead and create two resources. If it is a machine client then I would use content negotiation to get the required format.

And finally, be careful out there, since REST became a buzzword du jour, there is far more mis-informed content around than there is valid content.