REST APIs use Uniform Resource Identifiers (URIs) to address resources. On today’s Web, URI designs range from masterpieces that clearly communicate the API’s resource model like:
to those that are much harder for people to understand, such as:
Tim Berners-Lee included a note about the opacity of URIs in his “Axioms of Web Architecture” list:
The only thing you can use an identifier for is to refer to an object. When you are not dereferencing, you should not look at the contents of the URI string to gain other information.
—Tim Berners-Lee http://www.w3.org/DesignIssues/Axioms.html
As discussed in Chapter 5, clients must follow the linking paradigm of the Web and treat URIs as opaque identifiers. That said, REST API designers should create URIs that convey a REST API’s resource model to its potential client developers.
This chapter introduces a set of design rules for REST API URIs.
The rules presented in this section pertain to the format of a URI. RFC 3986 defines the generic URI syntax as shown below:
URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]
The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources. For example: ...