# REST API Naming Standards · REST-02

## Standard Metadata

- Area: API
- Owner: Backend Steering group
- Last reviewed: 2026-09-09
- Next review due from: 2026-12-01
- Enforcement: Code review
- Status: Active

## The appropriate HTTP verb must be used · REST-02.1 · **MUST** · **DEV**

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.

## Routes should be nouns · REST-02.2 · **SHOULD** · **DEV**

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`.

## Routes must contain the IDs they act upon · REST-02.3 · **MUST** · **DEV**

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.

## Routes should not have a depth greater than three · REST-02.4 · **SHOULD** · **DEV**

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 · REST-02.5 · **MUST** · **DEV**

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`.

## Route naming must be consistent · REST-02.6 · **MUST** · **DEV**

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.