One of the key ideas, and something that clients would typically expect when dealing with a RESTful API, is that each resource instance can be individually addressed via a Uniform Resource Identifier (URI). Since the format of URIs plays a significant role in conveying the API's resource model to the clients that will be consuming it, software engineers should always strive to come up with consistent URI naming schemes when designing new APIs or introducing new resource types to existing APIs.
The following opinionated set of conventions for naming resources can help you design APIs that are easier for end users to understand and work with:
- Resource names must always be nouns and never verbs or verb-like expressions. Verbs can be used as suffixes to indicate an action to be performed on a particular resource. For example, /basket/checkout triggers the checkout flow for the current user's basket.
- As an exception to the previously mentioned guideline, verbs related to CRUD operations should not be included as part of the resource URI; they can be inferred by the HTTP verb that's used when performing requests. In other words, instead of using a URI such as /users/123/delete to delete a user, clients should perform an HTTP DELETE request to /users/123 instead.
- When referring to a specific resource instance by name, a singular noun must be used. For instance, /user/account returns the account details for the currently logged-on user. While it might be tempting to use the singular noun pattern to refer to a particular item within a collection (for example, /user/123), it is recommended to avoid this practice as it tends to create inconsistent paths for CRUD operations.
- A plural noun must be used when referring to a collection of resources or a specific resource instance within a collection. For example, order/123/items would return the list of items in order with ID 123, while /users/789 would return information about the user with ID 789.
- Avoid appending trailing forward slashes (/) to the end of URIs. Doing so does not provide any additional information to clients and could lead to confusion; that is, is the URI complete or does it lack a portion of its path?
- RFC3986 [6] defines URIs as being case-sensitive. Therefore, for consistency purposes, it's good practice to stick to lowercase characters for URI paths. What's more, the use of hyphens (-) to separate long path segments can oftentimes result in paths that are much easier to read. Arguably, /archived-resource is much easier to read than /archivedresource.
The following table summarizes the combination of HTTP verbs and URI patterns for performing CRUD operations against a collection of products. The set of HTTP verbs and resource paths for working with a products resource are given as follows:
| HTTP Verb | Path | Expects (JSON) | Returns (JSON) | HTTP Status | Description |
| POST | /products | A product entry | The new product entry including its ID | 200 (success) or 201 (created) | Create a new product |
| GET | /products | Nothing | An array with product entries | 200 (success) | Get a list of products |
| GET | /products/:id | Nothing | The product with the specified ID | 200 (success) or 404 (not found) | Get product by ID |
| PUT | /products/:id | A product entry | The updated product entry | 200 (success) or 404 (not found) | Update product by ID |
| PATCH | /products/:id | A partial product entry | The updated product entry | 200 (success) or 404 (not found) | Update individual fields for a product by ID |
| DELETE | /products/:id | Nothing | Nothing | 200 (success) or 404 (not found) | Delete product by ID |
As you can probably surmise, the aforementioned patterns can also be applied to address resources that form hierarchies. For instance, to retrieve the set of permissions that have been assigned to the user with ID 123 within a security group with ID 789, /security-groups/789/users/123/permissions can be used as a path. In this example, the use of a forward slash to separate the security group and user resources implies the existence of a hierarchical relationship between them.