Clean URIs in REST

Question

I am designing a new web API for a client. I have not designed a so called RESTful API before and I am seriously having doubts about the validity of much of the hype about "what to do" and "what not to do".

Maybe it's me, but one thing I don't understand is why so much emphasis is put on the structure of the URI. Having the URI represent resources and what not.

The application then needs to "predict" what the URI contains, having lots of validity code and conditions dealing with an unnatural URL structure.

For centuries we have been using things like:

get_all_products.php

And:

get_product.php?id=1234

As long as everything is well documented, I cannot understand why we need to make the application even more complicated.

After all we're not creating APIs for search engines!

Answer 1

Actually most people completely misunderstand what Roy Thomas Fielding originally proposed and very few so-called RESTful applications are really RESTful.

In his blog post REST APIs must be hypertext-driven Roy is expressing his frustration with people calling their HTTP-based interfaces a REST API, when in fact they aren't.

One of the crucial elements of a RESTful application is the point that:

• A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). (Failure here implies that out-of-band information is driving interaction instead of hypertext.)

This is actually how most normal web sites behave.

What he is describing here is not what people believe they implement using URL rewrites and so-called single entry points in application and it has little to do with the subject!

If no representations exist beyond the initial URI, and no further links are provided by the responses of the server, there really is no way to determine how the application state transition can proceed beyond that point. It doesn't matter how you structure your URI and how predictable you make it, you're not creating a truly RESTful application.

Using an URI like:

https://www.example.com/api/1.0/products/

May enable the client to know that if “1234” is entered after the “products/” part, a specific product is fetched. And facilitating the methods of POST, PUT, and DELETE, may further enable the client to determine what actions can be performed on that particular resource, but it is still not a truly RESTful application because beyond that, there is no way to proceed using only server-provided choices.

What you really have is the out-of-band information driving interaction instead of hypertext, period!

Create a HTTP-interface, make sure you document everything with clear copy/paste examples (no assumptions), and just KISS, don't follow the hype!