Best Practices for Naming REST API URIs

External

• REST API Design Rulebook by Mark Masse, O'Reilly, Chapter 2. Identifier Design with URIs.

Internal

• REST and Hypermedia

Overview

REST APIs use Uniform Resource Identifiers (URIs) to address resources.

Use Forward Slash 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.

Example:

http:://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares

Use Nouns to Name URIs

A REST API endpoint has a URL at which it can be accessed: https://example.com. Subdirectories of the URL denote different resources, which are accessed with URIs.

In general, URIs should be named with nouns that specify the content of the resource, rather than using a verb for the function performed. This is because CRUD operations should already be specified in the HTTP request.

Example:

https://example.com/users

https:://example.com/users/{id}

Singular or Plural

In general, you should name the URIs that return collections using plural. The URIs that return an individual element will use the same prefix and an additional path qualifier, usually an ID, to designate the specific element.

Separate Words with Hyphens

When a REST API endpoint contains multiple words, separate the words with hyphens. It's a good way to make the URI easier to read and is a universal method that everyone can understand. It's generally accepted that a hyphen is clearer and more user-friendly than using underscores (first_name) or camel case (firstName), which is discouraged due to its use of capital letters.

TODO

• https://www.linkedin.com/advice/3/what-best-practices-naming-restful-api-endpoints
• https://blog.dreamfactory.com/best-practices-for-naming-rest-api-endpoints/