REST API Naming Standards & Best Practices

A Summary of REST API Naming Standards and Best Practices

Photo by Jacques LE HENAFF on Unsplash
  • 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)
  • CONNECT — 2 way communication (SSL/TCP)
    (No Request Body, Has Response Body)
  • 1xx => informational
  • 2xx => success
  • 3xx => redirection
  • 4xx => client error
  • 5xx => server error

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
HTTP Status Codes —
  • 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!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nil Seri

I would love to change the world, but they won’t give me the source code | coding 👩🏼‍💻 | coffee ☕️ | jazz 🎷 | anime 🐲 | books 📚 | drawing 🎨