REST API Design Rulebook

Chapter 2. Identifier Design with URIs

URIs

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:

http://api.example.restapi.org/france/paris/louvre/leonardo-da-vinci/mona-lisa

to those that are much harder for people to understand, such as:

http://api.example.restapi.org/68dd0-a9d3-11e0-9f1c-0800200c9a66

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.

URI Format

The rules presented in this section pertain to the format of a URI. RFC 3986^[19] defines the generic URI syntax as shown below:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

Rule: Forward slash separator (/) must be used to indicate a hierarchical relationship

The forward slash (/) character is used in the path portion of the URI to indicate a hierarchical relationship between resources. For example: ...