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.

Answer 2

I'm with S.Lott -- the Verb *should not* be in there, as you want to use the same URL for reading the record as for updating it for it to qualify as REST.

The content-type is something else to leave out, as it's the same record, but with multiple encoding formats. (Read up on FRBR for way more than you ever wanted to know about the issues of the distinction). The decision of which version to send in response can be handled with HTTP Accept headers.

The only one that I'm torn on is the version number, as I can't personally think of an appropriate HTTP header to handle that aspect of it. (Expect? Accept-Encoding? Pragma? Maybe even Upgrade, but you'd more frequently want to downgrade to an older version for compatibility reasons, I'd think) I'd probably have a version-less accessor which gave the most recent production version, but might consider have a version'd one for significant changes that weren't backwards-compatible.

update: the version issue probably depends on how much control you have over the clients connecting to your services ... if you have access from a wide public (which I don't), you might be more interested in backwards compatibility. Depending on the changes made, it's possible that you might also consider 'version 2' to be a completely new resource, rather than just a new 'version' of the original.

Answer 3

Versioning: I've usually seen this placed where you have it in your example url, and if a version isn't specified you should respond with the most recent production version. One consideration is whether to put the API version in your response string for client debugging purposes.

Response formats: The return format should be specified in the HTTP Accept header sent by the user agent.

Verbs in the request string: Absolutely not.

Answer 4

The verb cannot be put into the URL. That makes no sense. It's already in the request header. When you send a POST request that has GET in the URL, that's crazy.

The response format is usually best put into the URL because the headers don't provide a simple, unambiguous place to put that information.