# REST API Response Standards · REST-03

## 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

## GET Requests

### Successful GET requests must return a 200 (OK) status code · REST-03.1 · **MUST** · **DEV**

### Successful GET requests must return data · REST-03.2 · **MUST** · **DEV**

- If the GET request is for a specific ID (i.e. `/customers/{id}`), the response body should be a single object, which may be empty.
- If the GET request is not for a specific ID (i.e. `/customers` or `/customers?city=Leeds`), the response body should be an array containing zero or more objects.

## PUT Requests

### PUT requests that have been successfully processed must return a 204 (No Content) status code · REST-03.3 · **MUST** · **DEV**

### PUT requests that have been accepted to be processed asynchronously must return a 202 status code · REST-03.4 · **MUST** · **DEV**

## POST Requests

### POST requests that have been successfully processed must return a 201 (Created) status code · REST-03.5 · **MUST** · **DEV**

### Successful POST requests must include a location header · REST-03.6 · **MUST** · **DEV**

A location header should be included set to the url from which the resource can be obtained in future (i.e. the appropriate GET endpoint). ASP.NET Core provides the `CreatedAtAction` method to do this.

**EXCEPTION** This does not apply if the POST endpoint is for a search (e.g. where there are too many filters to capture in a query string so GET cannot be used).

### POST requests that have been accepted to be processed asynchronously must return a 202 status code · REST-03.7 · **MUST** · **DEV**

### Successful POST requests should return the data that has been created · REST-03.8 · **SHOULD** · **DEV**

The object created (including its ID) should be returned in the response body. If the object is large, or if it is infeasible to return the entire object, then the ID should be returned.

## DELETE Requests

### DELETE requests that have been successfully processed must return a 204 (No Content) status code · REST-03.9 · **MUST** · **DEV**

### DELETE requests that have been accepted to be processed asynchronously must return a 202 status code · REST-03.10 · **MUST** · **DEV**