What is REST and RESTful?

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.

The different request methods

GET and 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 DELETE.

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 POST, GET, PUT, PATCH, and 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, OPTIONS and HEAD are used more often than others.

I found the above explanation REST API Tutorial web site. Head over there for more detailed descriptions.

HTTP codes

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.

• 200 The request has completed successfully and results is returned.
• 201 The request has been fulfilled and resulted in a new resource being created.
• 204 The request has completed successfully, but nothing is returned.
• 404 The server has not found anything matching the Request.
• 409 The request could not be completed due to a conflict with the current state of the resource. e.g. resource already exist.
• 500 Internal server error, which can be used if the user is misusing the APIs.

Consider to use these HTTP codes for the following requests

POST Method

201 404 409

GET Method

200 404

PUT Method

200 204 404

PATCH Method

200 204 404

DELETEMethod

200 404

Hypermedia API

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.

[
  {
    "_id": "56f061f4364dd9282ead6e9e",
    "title": "My New Book",
    "genre": "Fiction",
    "author": "Hao",
    "__v": 0,
    "read": false,
    "links": {
      "self": "http://localhost:8000/api/books/56f061f4364dd9282ead6e9e"
    }
  },
  ...
]