REST API Naming Standards & Best Practices

Photo by Jacques LE HENAFF on Unsplash

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)
  • CONNECT — 2 way communication (SSL/TCP)
    (No Request Body, Has Response Body)

HTTP Status Codes

  • 1xx => informational
  • 2xx => success
  • 3xx => redirection
  • 4xx => client error
  • 5xx => server error
  • 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 —

Best Practices in API Naming

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




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

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Ultralearning Python & Pygame

Week 1 of Learning to Code HTML/CSS

Generate random test data at run time in JMeter

Models as a Tool for Deeper Insight

Golang struct size and memory optimisation.

System Design — Design a Monitoring System

Memory Efficiency and Space

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

Nil Seri

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

More from Medium

Where to Learn MongoDB in 2022

SpringBoot or Quarkus: Which framework is best for your project?

Spring Boot Vs Quarkus

Important Features — Java 9, Java 10, Java 11, Java 12, Java13, Java 14, Java 15, Java 16,, Java 17

Docker for Java Dev environment with IntelliJ and Gateway