REST API Response Standards · REST-03

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