Best Practices for Naming REST API URIs: Difference between revisions
No edit summary Tags: Manual revert Reverted |
No edit summary Tag: Manual revert |
||
| Line 8: | Line 8: | ||
=Overview= | =Overview= | ||
REST APIs use [[URI#Overview|Uniform Resource Identifiers (URIs)]] to address resources. | REST APIs use [[URI#Overview|Uniform Resource Identifiers (URIs)]] to address resources. | ||
=General URI Rules= | =General URI Rules= | ||
==Use Forward Slash to Indicate a Hierarchical Relationship== | |||
=Use Forward Slash to Indicate a Hierarchical Relationship= | |||
The forward slash (/) character is used in the [[URI#Path|path]] portion of the URI to indicate a hierarchical relationship between resources. Also see [[#Resource_Modeling|Resource Modeling]] below. | The forward slash (/) character is used in the [[URI#Path|path]] portion of the URI to indicate a hierarchical relationship between resources. Also see [[#Resource_Modeling|Resource Modeling]] below. | ||
| Line 20: | Line 19: | ||
</font> | </font> | ||
=A Trailing Forward Slash Should Not Be Included in URIs= | ==A Trailing Forward Slash Should Not Be Included in URIs== | ||
Every character within a URI counts towards a resource's unique identity. If the URIs differ, then so do the resources, and vice-versa. Even if the REST API implementation discards the trailing forward slashes, the definition of the REST API must communicate clean URIs. For example, an API implementation may redirect clients that use a forward slash to the URI without forward slash using a [[HTTP_Status_Codes#301_Moved_Permanently|HTTP 301]] response code. | Every character within a URI counts towards a resource's unique identity. If the URIs differ, then so do the resources, and vice-versa. Even if the REST API implementation discards the trailing forward slashes, the definition of the REST API must communicate clean URIs. For example, an API implementation may redirect clients that use a forward slash to the URI without forward slash using a [[HTTP_Status_Codes#301_Moved_Permanently|HTTP 301]] response code. | ||
=<span id='Hyphen'></span>Separate Words with Hyphens= | ==<span id='Hyphen'></span>Separate Words with Hyphens== | ||
When a REST API URI contains multiple words in a path segment, 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 [[#Underscore|underscores]] (first_name) or camel case (firstName), which is discouraged due to its use of capital letters. | When a REST API URI contains multiple words in a path segment, 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 [[#Underscore|underscores]] (first_name) or camel case (firstName), which is discouraged due to its use of capital letters. | ||
=<span id='Underscore'></span>Do Not Use Underscores= | ==<span id='Underscore'></span>Do Not Use Underscores== | ||
One practical reason is that the underscored may get partially obscured in the UIs that render clickable URIs, depending on the fonts that are used. To avoid this, use [[#Hyphen|hyphens]] to separate words. | One practical reason is that the underscored may get partially obscured in the UIs that render clickable URIs, depending on the fonts that are used. To avoid this, use [[#Hyphen|hyphens]] to separate words. | ||
=Prefer Lowercase Letters= | ==Prefer Lowercase Letters== | ||
The URIs are case-sensitive, except for the scheme and host components. | The URIs are case-sensitive, except for the scheme and host components. | ||
Lowercase is preferred, if practical, because capital letters can sometimes cause problems. | Lowercase is preferred, if practical, because capital letters can sometimes cause problems. | ||
=File Extensions Should Not Be Included in URIs= | ==File Extensions Should Not Be Included in URIs== | ||
A REST API should not include artificial file extensions in URIs to indicate the format of a message's entity body. Instead, they should rely on media type, as communicated through the <code>Content-Type</code> header. | A REST API should not include artificial file extensions in URIs to indicate the format of a message's entity body. Instead, they should rely on media type, as communicated through the <code>Content-Type</code> header. | ||
Revision as of 00:56, 14 February 2024
External
- REST API Design Rulebook by Mark Masse, O'Reilly, Chapter 2. Identifier Design with URIs.
Internal
Overview
REST APIs use Uniform Resource Identifiers (URIs) to address resources.
General URI Rules
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. Also see Resource Modeling below.
Example:
http:://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
A Trailing Forward Slash Should Not Be Included in URIs
Every character within a URI counts towards a resource's unique identity. If the URIs differ, then so do the resources, and vice-versa. Even if the REST API implementation discards the trailing forward slashes, the definition of the REST API must communicate clean URIs. For example, an API implementation may redirect clients that use a forward slash to the URI without forward slash using a HTTP 301 response code.
Separate Words with Hyphens
When a REST API URI contains multiple words in a path segment, 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 underscores (first_name) or camel case (firstName), which is discouraged due to its use of capital letters.
Do Not Use Underscores
One practical reason is that the underscored may get partially obscured in the UIs that render clickable URIs, depending on the fonts that are used. To avoid this, use hyphens to separate words.
Prefer Lowercase Letters
The URIs are case-sensitive, except for the scheme and host components.
Lowercase is preferred, if practical, because capital letters can sometimes cause problems.
File Extensions Should Not Be Included in URIs
A REST API should not include artificial file extensions in URIs to indicate the format of a message's entity body. Instead, they should rely on media type, as communicated through the Content-Type header.
Authority Rules
APIs Should Use Consistent Subdomain Names
The top-level domain and first subdomain name (example: accounting.example.com) should identity the service owner. The full domain name of an API should add a subdomain named "api": api.accounting.example.com.
Developer Portal Names
Many REST APIs have an associated website, known as developer portal, to help on-board new clients with documentation, etc. Conventionally it is named using the "developer" subdomain: developer.accounting.example.com.
Resource Modeling
The URI path conveys a REST API's resource model, which each forward slash separated path segment corresponding to a unique resource within the model hierarchy. Resource modeling establishes the key API's concepts, and it is similar to data modeling in a relational database or class hierarchy modeling in an object-oriented system.
For example: http:://api.directory.exmaple.com/departments/marketing/teams/{id} indicates that each of these URIs should also identify an addressable resource:
http:://api.directory.exmaple.com/departments/marketing/teams http:://api.directory.exmaple.com/departments/marketing http:://api.directory.exmaple.com/departments http:://api.directory.exmaple.com
Use Nouns to Name Resources
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}
Prefer 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.