RESTful API Design Best Practices (Principles)

  • Simplicity to build and adapt.
  • Low resource usage.
  • Explicit processes or process instance.
  • The client does not need to manage routing information, only initial URI enough.
  • The client can depend on only a generic listener interface.
  • REST allows various data formats.
  • High-performance gain over SOAP. (faster and less bandwidth usage).
  • Comply with HTTP protocols.

Microservices vs RESTful

  1. Fetch all employees.
  2. Fetch employee by id.
  3. Save employee
  4. Update employee
  5. Fetch employee by department
  6. Delete employee by id
  1. Simple API endpoints
  • Do not use long URI patterns with verbs( this is not mandatory, but best practice).
GET /getAllEmployees
GET /getEmployees/1234
POST /addEmployee
// below URI must return all employees belongs to HR department/departments/HR/employees
  • GET — Fetch a resource or collection of resources.
  • POST — To save/create a resource or collection of resources.
  • PUT/PATCH — To update the existing resource or collection of resources.
  • DELETE — To delete/remove the existing resource or the collection of resources.
GET /employees      // use plural nouns empoyees instead of employee
GET /employees/1234
POST /employee // send the data with POST object and return the created objectDELETE /employee/1234 // should delete resource from the data store or collection
  1. Success (starting with numeric 2, 2xx)
  2. Redirection (starting with numeric 3, 3xx)
  3. Client Error (starting with numeric 4, 4xx)
  4. Server Error (starting with numeric 5, 5xx)

Most frequently used error codes in RESTful APIs

  • 200-Ok HTTP response for every success for GET, PUT or POST.
  • 201-Created HTTP response for success and resource had created and not response body or response body is empty.
  • 204 No Content HTTP response for the request is successfully accepted and send acknowledge to the client.
    DELETE request can be a good example for this.
DELETE /department/HR/employee/1234  or
DELETE /employee?dept='HR'&id=1234
  • 304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.
  • 400 Bad Request HTTP response for the request by the client was not processed, as the server could not understand what the client is asking for.
  • 401 Unauthorized HTTP response for the client is not allowed to access resources and should re-request with the proper authentication or credentials.
  • 403 Forbidden HTTP response for the request is valid and the client is authenticated, but the client is not allowed access the page or resource for any other reason. E.g sometimes the authorized client is not allowed to access the directory on the server.
  • 404 Not Found HTTP response for the requested resource is not available to access.
  • 410 Gone HTTP response for the requested resource is no longer available to access or permanently moved.
  • 500 INTERNAL SERVER ERROR — HTTP response indicates that there might be a system failure.
  • 502 BAD GATEWAY — HTTP response indicates that the server received an invalid response from the upstream server/system.

7. Versioning the APIs

/V2/employees  // Major version
/V2.x.x/employees // patch/minor or dev versions

8. Other useful operations (Filtering, pagination, Sorting)

// default sort will ne ASC. you only need mention you need descending order./emplyees?sort='dsc'// pagination can be achieved by limit params/employees?limit=10  // retrieve next 10 resource collection/employees?page=5    // you can have pagination logic in server side// Filtering can  be achieved by parameters

9. Decide support request/response formats

10. Use proper/identifiable error messages.

"error": {
"code": 1234,
"type": "ResourceNotFoundException",
"message": "(#1234) Employee that you requested is not found",
"trace_log": " detailed exception if you need to send to the client side"


11. User standard specification

Thank you

More reads




Software Architect-Singapore( MSc in Information Security, BSc MIT, AWS,CCNA SECOPS, Certified Systems Architect)

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

Recommended from Medium

AWS Certified Solutions Architect Professional — Identity & Federation — IAM

GameDevHQ Professional Developer Program Part 3: 2.5D Platformer

KYVE Korellia Testnet!

A practical way to automate testing Oauth 2.0 Service

Teaching Java Prepares Students for Next Generation Workforce

An in-depth guide to Vim!

Challenges and Issues of Embedded Software Development

How to create Netflix style input box

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

Dilanka Muthukumarana

Software Architect-Singapore( MSc in Information Security, BSc MIT, AWS,CCNA SECOPS, Certified Systems Architect)

More from Medium

Dynamic Linkage to a z/OS Native Library in Java

Leading a world-class API experience

Register User Architecture

A Quick Way to Document and Test Spring Boot RESTful Services with Swagger UI