REST API Naming Standards & Best Practices

3 min readFeb 13, 2022

A Summary of REST API Naming Standards and Best Practices

HTTP Request Methods

POST — Create
like form submit, to send data to server. (PUT is idempotent, POST is not)
GET — Read
(No Request Body)
PUT — Update / Replace
(No Response Body)
Create or replace (can return 200/204/201)
PATCH — Update / Modify
DELETE — Delete
(May Have Request / Response Body But Generally No)
OPTIONS — Permitted Communication Operations
(No Request Body, Has Response Body)
HEAD — Headers
(No Request / Response Body)
for file size or content length
TRACE — Debugging
(No Request / Response Body)
loopback
CONNECT — 2 way communication (SSL/TCP)
(No Request Body, Has Response Body)

Popular Status Codes and Their Reasons:

100 -> Continue
200 -> OK
201 -> Created
204 -> No Content
301 -> Moved Permanently
400 -> Bad Request => validation errors
401 -> Unauthorized => when authorization fails
403 -> Forbidden
404 -> Not Found
405 -> Method Not Allowed
412 -> Precondition Failed
429 -> Too Many Requests => can use for throttling
500 -> Internal Server Error
503 -> Server Not Available

Always think about the consumers.
Use proper HTTP request methods & Return status codes accordingly.
Prepare both your success and error response models (Exception Handler with “@ControllerAdvice” in Spring Boot).
Write documentation (Swagger or OpenAPI)
No secure info in the URI
Use plurals (can use hyphen separated lower-case )
/user ❌
/users ✔️
/sea-cargo ✔️
Use nouns for resources
/delete-account ❌
DELETE /accounts/845 ✔️
Define a consistent approach
GET /account/256/purchases
Semicolon, or, more frequently, the comma should be used in lists
/users/{id1},{id2} ✔️
Use camelCase for parameters, Hyphenated-Pascal-Case for HTTP Headers
Add “Accept” Request Headers
Support versioning
in URI as /v1/account or in a header parameter as X-API-VERSION
HATEOAS => Hypermedia As The Engine Of Application State
In summary, you send API Urls in the response for the consumer to use for showing the next steps (actions) from there. Like, in a web page, you list products and you click on a product to get its details. In your list products’ API response, you also return GET API Urls for each product so front-end does not have to build up the urls.
loose coupling => If a consumer of a REST service needs to hard-code all the resource URLs, then it is tightly coupled with your service implementation.

Happy Coding!