Best Practices for Naming REST API URIs

From NovaOrdis Knowledge Base
Jump to navigation Jump to search

Internal

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/user/{id}

Singular or Plural

In general, you should name the URIs that return collections using plural, and URIs that return an individual element with singular.

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