Nouns
Use nouns for resource names. Use nouns to represent resources. For example, use /orders instead of /create-order. The HTTP GET, POST, PUT, PATCH, and DELETE methods already imply the verbal action.
Plural Nouns
Use plural nouns to name collection URIs. In general, it helps to use plural nouns for URIs that reference collections. It’s a good practice to organize URIs for collections and items into a hierarchy. For example, /customers is the path to the customer’s collection, and /customers/5 is the path to the customer with an ID that equals 5. This approach helps keep the web API intuitive.
Relationships between different types of resources
For example, the /customers/5/orders might represent all of the orders for customer 5. You can also approach the relationship in the other direction by representing the association from an order to a customer. In this scenario, the URI might be /orders/99/customer. However, extending this model too far can become cumbersome to implement. A better approach is to include links in the body of the HTTP response message so that clients can easily access related resources. Use Hypertext as the Engine of Application State (HATEOAS) to enable navigation to related resources describes this mechanism in more detail.
Simple Relationships
Avoid requiring resource URIs that are more complex than collection/item/collection.
Simple Relationships Contd..
In more complex systems, you might be inclined to provide URIs that allow the client to navigate through several levels of relationships, such as /customers/1/orders/99/products. However, this level of complexity can be difficult to maintain and is inflexible if the relationships between resources change in the future. Instead, try to keep URIs relatively simple. After an application has a reference to a resource, you should be able to use this reference to find items related to that resource. You can replace the preceding query with the URI /customers/1/orders to find all the orders for customer 1, and then use /orders/99/products to find the products in this order.
Non Resources APIs
It might not be possible to map every operation implemented by a web API to a specific resource. You can handle these nonresource scenarios through HTTP requests that invoke a function and return the results as an HTTP response message.
For example, a web API that implements simple calculator operations such as add and subtract can provide URIs that expose these operations as pseudo resources and use the query string to specify the required parameters. A GET request to the URI /add?operand1=99&operand2=1 returns a response message with the body containing the value 100.
However, you should use these forms of URIs sparingly.
Pagination
GET /orders?limit=25&offset=50
Pagination divides large datasets into smaller, manageable chunks. Use query parameters like limit to specify the number of items to return and offset to specify the starting point.
Filtering
GET /orders?minCost=100&status=shipped
minCost: Filters orders that have a minimum cost of 100.
status: Filters orders that have a specific status.
Sorting
Sorting allows clients to sort data by using a sort parameter like sort=price.
The sorting approach can have a negative effect on caching because query string parameters form part of the resource identifier that many cache implementations use as the key to cached data.
