REST API Naming Standards · REST-02

Depending on the operation being performed by the API, the following HTTP verbs must be used:

• GET: Read-only operation that returns data
• PUT: Write operation that updates existing data
• POST: Write operation that creates new data
• DELETE: Write operation that removes existing data

It is important to note that GET, PUT and DELETE endpoints should be idempotent. If an endpoint is not idempotent (e.g. as well as updating/deleting/retrieving data, it also creates some data) then POST should be used.

Nouns should primarily be used when building routes.

Simple routes must be based on nouns rather than verbs, e.g. /customers rather than /getCustomers, where the nouns are ‘resources’.

An exception to this rule would be that verbs can be used to represent a specific action to be taken on a resource, usually being specified at the end of the route, e.g. movies/{id}/play.

Any endpoint that is performing an action on a specific item must specify the ID in the route, e.g. /customers/{id}. This applies to GET, PUT and DELETE requests.

If resources have children then it is often appropriate to reflect this in the route. For example, if each customer has a collection of addresses, then a good route would be /customers/{id}/addresses, where the {id} placeholder is the ID of the customer.

Limit the depth to which child resources are nested in a route to three levels, wherever possible.

For example, one/{idOne}/two/{idTwo}/three/{idthree} would be appropriate however one/{idOne}/two/{idTwo}/three/{idThree}/four should be restructured, possibly by making the resource two the root of the route.

Controllers must contain the endpoints for a single resource (following the single responsibility principle).

For example, endpoints at the root of customers (GET /customers/{id}) would be in the CustomersController. Endpoints for child resources should be in their own controller, meaning GET customers/{id}/addresses would be in the AddressesController.

Kebab-cased urls are preferred, e.g. /order-items rather than /orderItems.

When defining routes for a controller avoid using [Route(“[controller]”)], as this couples the url to the name of the controller. It is therefore possible to break clients by renaming a controller.