Question

I’m reading RESTful Web Services Cookbook and there is a complete chapter about the identification of resources. The author emphasizes the importance of the identification process. Why is it so important?

EDIT: “REST APIs must be hypertext-driven” by Roy Fielding is quite interesting. I must confess that I don’t fully understand what Roy Fielding is actually talking about – due to my ignorance of course – but it seems to be relevant to my questions.

Answer 1

Fielding doesn’t have much to say on selecting identifiers.

5.1.5 Uniform Interface

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. […] REST is defined by four interface constraints: identification of resources [emph. added]; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.

5.2.1.1 Resources and Resource Identifiers

REST uses a resource identifier to identify the particular resource involved in an interaction between components. […] The naming authority that assigned the resource identifier, making it possible to reference the resource, is responsible for maintaining the semantic validity of the mapping over time (i.e., ensuring that the membership function does not change).

Traditional hypertext systems, which typically operate in a closed or local environment, use unique node or document identifiers that change every time the information changes, relying on link servers to maintain references separately from the content. Since centralized link servers are an anathema to the immense scale and multi-organizational domain requirements of the Web, REST relies instead on the author choosing a resource identifier that best fits the nature of the concept being identified. Naturally, the quality of an identifier is often proportional to the amount of money spent to retain its validity, which leads to broken links as ephemeral (or poorly supported) information moves or disappears over time.

This seems to fit the main point of “Cool URIs Don’t Change“, that while the particular pairing of identifier and resource might change, the identifier itself should always exist once created. Fielding’s other point regarding identifiers is that they should present a uniform interface. HTTP URLs achieve this in part with their hierarchical nature (at least, they’re supposed to be hierarchical). However, URIs in general don’t have to be hierarchical.

A uniform interface and hierarchical identifiers can simplify one of the primary server functions: mapping identifiers to resources. At it simplest, representations are stored in the same hierarchy as identifiers when the mapping performed is to prepend the document root to the request URI, though web services rarely use the simple mapping.

The book you’re reading suggests its own reason for devoting a chapter to picking identifiers:

Of all the aspects of designing a RESTful web service, such as identification of resources, choice of media types and formats, and application of the uniform interface, resource identification is the most flexible part.

With more choices comes more work. If identifiers were rigid, offering few choices, you’d have less to think about. Furthermore, since URIs are so visible and you’re going to have to live with your choices for a long time, you’d better put some thought into them.