It’d be annoying, but you could switch integer IDs to UUIDs by creating a separate table to do that mapping, and forcing all new records to be constructed with UUID only. Then, just use a permanent redirect.

If the client is instead meant to look up “sample project” by name, that raises two questions: First, is “name” really unique and guaranteed to be unchanging? If not, how will your client find it after someone renames or duplicates it? And if so, why not use it in the URL, instead of something cryptic like a UUID or an autoincrement ID?

I tend to agree that you should provide standard navigation (as you suggest) in addition to sane URLs, and I would take it a step further and suggest that it be done in HTML, with microformats. Certainly, once I have a URL to a resource, I should be able to navigate to subresources and related resources via hyperlinks, not by constructing URLs. But at the same time, the entire purpose of a URL is not to be a transient link between documents, but a Universal Resource Locator — universal, and actually relevant to the current location of the resource.

Specifically: “Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations.”

200++ TV CHANNELS http://WWW.4URTV.BLOGSPOT.COM

SEND FREE SMS IN PAKISTAN ANY NETWORK UNLEMITED & SEND FREE SMS IN WORLD http://WWW.4URFREESMS.BLOGSPOT.COM

FREE CHAT ROOM IN PAKISTAN & AND ALL WORLD http://WWW.4URCHATROOM.BLOGSPOT.COM

http://WWW.PAKDESK.TK

I like your article and I understand your point of view and the need for “getting it right”. But I still have a couple to doubts, some even related to past comments in this entry.

First issue…

For instance, Michael S. asks in comment #6 above about searching to avoid clients to retrieve (GET) all resources of a given kind to then find/navigate to a specific one.

You then answered in comment #13 with “suggestions”. But since clients ignore any specifics about the API of a system, and need only to know a single entry point with hyperlinks to the available services, how are clients suppose to “discover” or learn how to search? I mean, they might learn that product resources can be find at “/products”, but if they want to filter or search within all products, how do they know what querystring parameter to use, or any other implementation specification to search this resources?

And the second issue, which is not a doubt but a rant. Ruby on Rails, which on one hand has contributed a lot by “spreading the word” of restul interfaces (I first knew about REST from rails) but today with your article and roy fielding’s original dissertation about it, I have learned that rails, far from helping, has spread the wrong idea about what a RESTful interface is, because rails is not [fully] compliant.

Rails relies on a predetermined URI structure, but when a design implementation changes this structure, all clients get broken. ActiveResource, for instance, relies heavily on this. And I have learned today all this and I feel so bad. It’s preferable not to adopt it at all, than to wrongly adopt it.

Still, there may be occasional valid reasons to diverge, usually in especially complex cases: Amazon certainly thought out their S3 authentication scheme carefully, though it is outside this guidance.

I’m not convinced about versioned APIs. I fully agree this practice should be minimized, and I’ve seen it abused. But I also know of lots of cases where the API significantly and incompatibly differs and there is a user base reliant on a previous version. I am imagining a developer with a widely used REST API reads this blog post and goes back and rethinks their design (e.g. minimizing the starting points) — content negotiation alone might not cover the differences.

So if a developer is not sure their REST API is correct, final, or long-term supportable, proactively introducing a version number is probably a good defensive practice giving you more flexibility to get it right in the future. IIRC Richardson and Ruby had stuff to say about this in their O’Reilly book, which has led many developers to REST, and may account for the prevalance of this practice.