How to Implement Correct REST API & RESTful Web Services?
It is always easy to assume that you’ve understood something before someone showed you the correct solution. When I tried to follow someone’s tutorial on how to create REST APIs using node.js and express.js, I found out I didn’t get REST APIs completely right. I have also found out a few more things on the side, which I will also be sharing in this blog.
While REST stands for Representational State Transfer, which is an architectural style for networked hypermedia applications, it is primarily used to build Web services that are lightweight, maintainable, and salable. A service based on REST is called a RESTful service.
So REST is a method for client side to communicating with the server side. The requests are structured in such a way that they often can be seen as black-box APIs, where anyone can make requests to the server with simple HTTP requests. This is how people can create their own clients for Twitter, Github and etc. Because all they need are the APIs released by companies like Twitter.
A more traditional method is to use AJAX call to fetch XML formatted data from server. But XML is replaced by JSON in REST APIs, due to better readability and usability.
POST are the most common ones used, but there are many others which are not fully and correctly utilized. I have see project using
GET when they should be using
POST, or using
POST when they should be using
The HTTP verbs comprise a major portion of our “uniform interface” constraint and provide us the action counterpart to the noun-based resource. The primary or most-commonly-used HTTP verbs (or methods, as they are properly called) are
DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. There are a number of other verbs, too, but are utilized less frequently. Of those less-frequent methods,
HEADare used more often than others.
I found the above explanation REST API Tutorial web site. Head over there for more detailed descriptions.
The other thing I realized from the tutorial is that I really didn’t know what I was doing with HTTP codes. There is a whole list which can be found on official W3 site. But following on from HTTP request methods, REST API Tutorial site also listed out the common HTTP codes as well.
200The request has completed successfully and results is returned.
201The request has been fulfilled and resulted in a new resource being created.
204The request has completed successfully, but nothing is returned.
404The server has not found anything matching the Request.
409The request could not be completed due to a conflict with the current state of the resource. e.g. resource already exist.
500Internal server error, which can be used if the user is misusing the APIs.
Consider to use these HTTP codes for the following requests
This opened up a brand new door for me in terms of how API should be implemented for the sake of other developers. APIs can be messy, especially if it is not well documented. I have mentioned above that black-box API exists, where the developer using it does not need to know what is going on behind the scenes. “But how do you know how the API works?” you may ask. Well, hypermedia API is mention to help with that.
The example below shows what was returned from a
GET request. Many book results has been returned. Normally, the developer using this will need to go read the documentation in order to figure out how to query the book by ID. But in this case, within links attribute of the object, you can find a link. This is just to show a point, but in a production environment, this API should return a list of links, providing key insight into what you can actually do with the products returned. This will help people to understand the API without reading any additional docs, which means the usability is massively improved.