Over time, I came to realize that restful service that give full details of every response are the quickest to understand and easy to work with. This Restful API Service have four things in common. The aim of this post is to make you understand how to write a clean response and the correct data to expose for every API request to your endpoint.
Clean and well explain Restful APIs have four sets of items in their response which include
- The response message
- Status code
- Data
- Link to the newly created resource
- Response Message
Every request to your endpoint, the response should come alone the message that explain the action they took place whether it is successful or not. The message gives an idea the kind of action that took place, with the message, the developer using your API will know exactly how to utilize it in the front end.
- Status Code
For every request made, it goes through a series of network protocol before reaching the endpoint, at every stage the is a status code that explains what happens, over time if there are any issues along the network, a specific status code is sent back that explains it.
In a case where the request was successful, it is your turn to send back a correct status code [i.e status 200 ok, for success] so the network tap will be kept in sink with the status of the request from your end.
- Data
For every request to your API, the action is carried out, be it either get, create, update or delete a resource, it is expected that you return a data, be it in the form of ID of the resource that was deleted or resource field that was created or an update request that is issued.
by default when a get request is a carryout, You are sending back feed of data from a particular resource.
-Link to the resource
In create and get request, link to the particular resource is needed in a response, this way, anyone consuming your API
will have easy access to a single resource link that he or she can use in his frontend thus removing the hurdle of finding a way to access a single resource.
Having these four key variants in your response has proven to be the most effective way to design Restful API, that people will easily understand and work with.
if you have anything you will like to share with regards to this post, please do share using the comment box below
Thank you