Skip to main content

REST API Design In Practice

Greetings

REST API designing and modeling is a beautiful art one can master. I was lucky to work in such an environment where we gave a lot of effort to design better APIs by following proper guidelines. Out of all the companies I worked for, it had the best guide on REST design. I thought to share my learning and some thoughts on REST API designing decisions one can take.

The product domain is healthcare hence I am referring to the FHIR standard here as it is more generic and common for anyone. I choose the FHIR appointment as the discussion point.

Challenges

These are some of the challenges for any project that we will face.
  • There is a lot of logic on the client and there are other structural problems after many years of development
  • Complex logic and difficult to grasp
  • Multiple modules are impacted
  • Support new requirements while preserving the running system behavior
  • Deliver on time
  • Need to support multiple consumers

REST practices in short

In today's world, it is a must to have REST knowledge. At least the basic design ideas should be grasped.
  • Used correct HTTP methods - GET (retrieval), POST (new resource), PUT (update), DELETE (delete)
  • Used correct HTTP status codes - 200 (success), 201 (created), 204 (no content), 400 (client error), 404 (not found), etc
  • Used standards naming conventions. - plurals, kebab-case, nouns, camelCase segments
  • Used proper business resources - ex: Appointment, Patient
  • Used proper/common error envelop
  • Proper documentation - Swagger/Open API
POST /pet-store/cats
GET /pet-store/findByName

API first development

Unlike in earlier days, there are standards and tools to support REST now. Most companies use Open API Specifications so we do too. Designing the API first before starting the development gives us a lot of advantages. To name a few;
  • Clear out the business requirements early
  • Better use of tooling to auto-generate codes based on the specification
  • Better business endpoints
  • More focus on the business than the technical details
  • Define clear domain boundaries

Business endpoints

For us, developers, it is technical, but in reality, this is business. Hence having an endpoint to address business use cases give more meaning. To evolve the domain and get a better grasp on what we are doing. Hence, instead of CRUD-like APIs, we have finer-grained business APIs.

Minimum viable solutions

One of the earliest decisions we took is to provide MVP solutions and add the rest of the features incrementally. This way, consumers always have something usable. MVP solution mostly involved mandatory fields and mandatory validations.

Example endpoints

Following FHIR standard, we can define a few endpoints for doctor booking as below.
POST /appointments/planned
POST /appointments/booked
PUT /appointments/{id}
GET /appointments/{id}
POST /appointments/{id}/bookings
POST/ appointments/{id}/cancellations
GET /appointments/findByPatient

What is with this naming?

As you can see above, proper REST practices have been used when defining these. However, there are a few notable ideas also present.

Retrieval operations

Retrieval operations can be categorized as per the use.
GET /appointments/{id} - Retrieve single resource
GET /appointments - Retrieve all resources

Search

Search APIs can be named in 2 ways according to how we want to handle resource not-found situations.
GET /appointments/getByPatient - Return 404 status code when resources not found
GET /appointments/findByPatient - Return 200 status code and empty list when resources not found
It depends on what you want to achieve and how complex your system is. As all the consumers need to handle 404 and related errors, it is nicer to return 200 with an empty list.

Create resources in a specific status

The naming convention here is to use the ending state.
POST /<plural resource name>/<state>
POST /appointments/planned

When the status changes

When transitioning from one status to another, it is needed to define it with the same meaning. Hence the reified naming should be used.
POST /<plural resource name>/<reified operation>
POST /appointments/{id}/bookings - plan to book transition

Conclusion

It is important to follow proper guidelines when designing REST APIs as it increases business value. There can be subtle differences between companies regarding the convention. Even so, we should follow the same convention throughout the same project.

Happy learning ☺

References

https://www.hl7.org/fhir/appointment.html

Comments

Post a Comment