Skip to main content

REST API

Endpoints should be based on resources, not on actions. The request method determines the action.

Use nouns (not verbs) in the path, since the request method already has the verb.

  • Good: https://example.com/users
  • Bad: https://example.com/create-user

Limit levels/nesting to maximum collection/<id>/collection.

  • Good: https://example.com/employee/3/tasks
  • Bad: https://example.com/company/4/employee/3/tasks

CRUD Routes

MethodRouteActionHTMLDescriptionSuccess CodeFailure CodeRequest BodyResponse Body
GET/usersindexList all users200 OK404 Not FoundResource list
GET/users/:idshowGet single user200 OK404 Not FoundResource
GET/users/newnewRender create form200 OK404 Not FoundHTML
POST/userscreateCreate new user201 Created400 Bad Request or 422 Unprocessable Entity if malformed, 409 Conflict if duplicateResourceLocation header + status - see below
GET/users/:id/editeditRender edit form200 OK404 Not FoundHTML
PUT/users/:idupdateUpdate user, or create if it doesn't exist200 OK or 204 No Content if updated, otherwise 201 CreatedResourceOptional
PATCH/users/:idupdateUpdate user, partial200 OK or 204 No Content404 Not FoundResourceOptional
DELETE/users/:iddeleteDelete user200 OK or 204 No ContentEntity describing status or nothing

Notes:

  • Use 204 No Content if the response has no body, otherwise 200 OK.
  • 202 Accepted can be used if the operation is accepted but action is deferred.

GET

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET

Request has no body, response does.

POST

Response should have "a Location header field that provides an identifier for the primary resource created and a representation that describes the status of the request while referring to the new resource(s)".

Source: https://stackoverflow.com/a/49054482/4034572

Also see: https://stackoverflow.com/questions/1226810/is-http-post-request-allowed-to-send-back-a-response-body

If the request is malformed (eg a missing parameter) you can use either 400 Bad Request or 422 Unprocessable Entity. See:

POST if the resource already exists (eg duplicate username or email)

409 Conflict

PUT

POST to a collection, PUT to a resource source

PUT creates a resource if it doesn't exist, or updates it if it does (UPSERT).

PATCH

Return 404 if the resource does not exist.

According to https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#742-patch it should support UPSERT.

DELETE

https://stackoverflow.com/questions/6439416/status-code-when-deleting-a-resource-using-http-delete-for-the-second-time

https://stackoverflow.com/questions/6581285/is-a-response-body-allowed-for-a-http-delete-request

https://stackoverflow.com/questions/25970523/restful-what-should-a-delete-response-body-contain

CRUD Examples

Fake API

https://httpstat.us

REST vs RPC

https://cloud.google.com/blog/products/application-development/rest-vs-rpc-what-problems-are-you-trying-to-solve-with-your-apis

the RPC model makes it very simple and direct for programmers to write a procedure in one program and call it from another. This is one of the characteristics that makes RPC so popular, but it also makes it easy for technology and use-case assumptions to flow easily from one application to the other, thereby coupling the two and making the system brittle.

Guidelines

Examples