by Youming Zhang
You may have heard about REST and RESTFUL API but to understand this you need to know what REST stands for — REpresentational State Transfer. REST architecture is the style of communication between networked systems on the worldwide web. A Representation is a resource a client is trying to access such as data or webpage elements. Then the representation will assign the client with a state whenever the client requests a new representation. The state changes or transfers to a new state after the client’s request (web page updates).
Why do we need a REST API? Nowadays, we have many different devices on the web and they use different operating systems as well. So we need a one-stop, clear, and readable protocol to handle the request from different users on different devices, and an effective way to use that protocol. Roy Thomas Fielding described how HTTP and WWW should be seen in a RESTFUL way in his paper Architectural Styles and the Design of Network-based Software Architectures.
“REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, the generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems”.
With REST, a client doesn’t need to know anything about how a system works, it only needs to know the interface (API) which describes it. Similarly, a server doesn’t need to know anything about the client, as long as the client communicates correctly using the API. REST, therefore, provides the independent development of components. For example, I am currently working on a web application but our backend and database need some development. However, our front end is not affected by the malfunction of the database and backend. I can still develop the front end without any problems except HTTP requests. For the figure 1 below, you can see that clients send HTTP requests (explained later in this paper) through the HTTP API and the API will communicate with the database server to query the data. Then the API either sends back the data with a successful response or sends failed response code.
REST API Basics
Now we know what REST is. What is an API? API stands for an application programming interface. A REST API is more like a collection of functions you can call to request data from the server. REST API endpoints are URLs you can access directly from the browser. Depending on the server program, they will return a JSON string or an HTML page or data in another format. Let’s say Tom wants you to buy a flat white for him. He wants something from Starbucks. How much you paid, he doesn’t care. He only wants you to bring the flat white coffee to him. In order to satisfy his request and don’t get an F in his class, you went to Starbucks and bought a coffee and brought the coffee back to Tom. He is satisfied and gave you an A.
A REST API that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. Clients only need to know the URL for HTTP requests. Just like you satisfy Tom’s needs and bring a coffee back to him without him knowing which shop you went to and how much you paid.
For an application to be considered as RESTFUL. It has to satisfy these requirements according to Dr.Fielding.
Clients and Servers
As we discussed before, the client and server must be separated from each other and they can evolve individually. Changes can be made on a front-end web application (a client) and that does not affect the data structure and backend (the server). The same applies to the server, unless you are adding new features. This lets client and server change independently of the other and allows your organization to grow quickly and efficiently.
Statelessness
Any request from a client only accesses the data from the backend server but does not change the state of that information on the server. Requests can be made independently from each other as shown in figure 1. A RESTful API requires that any state is stored on the client—not on the server in order to reduce memory requirements and keep your application as scalable as possible.
Caching
Because a stateless API could possibly handle large loads of incoming requests from multiple clients, the client should be able to cache data about the representation of the system’s state that it received. This will not only greatly reduce the number of interactions with your API, reducing internal server usage, but also provide your API users with the tools necessary to provide the fastest and most efficient apps possible.
Uniform Interface
The key to decoupling clients from servers is having a uniform interface that allows them to evolve by themselves instead of relying on the server-side. The uniform interface lets the client talk to the server in a single language, independent of the architectural backend of either.
Layered System
The architecture of a REST system should let each layer have individual functionalities. The most commonly used layered system architecture is called “Model View Controller”.
Figure 2 shows a MVC system. The model defines the data structure and data logic. The controller manages incoming requests from the clients via the API and data responses. The controller, then, is the server program itself. The view provides a display of the data and a responsive UI. The view is what the client displays. Each layer is independent of the other but also interacts with each other. It helps create a more robust application.
Code On Demand
Code-on-Demand (COD) is the only optional constraint in REST. At the time REST was designed, the web was mostly just static documents and the only “web client” was the browser itself. Now it’s commonplace for JavaScript-powered web apps to be consuming REST APIs. This is an example of code on demand – the browser grabs an initial HTML document and supports <script> tags inside that document so that an application can be loaded on-demand. Clients can thus gain new functionality through client-side JavaScript code, loaded via HTTP request from the server.
REST API In Action
The best way to learn REST API is to see some real examples. I will use the GitHub REST API as an example. The program making requests is called Postman. It is an easy-to-use application to test/send HTTP requests. It is more visual and information is more uniform than looking at a console. We need to define some key concepts.
HTTP Methods
In web applications, the methods often used for requests are called HTTP verbs(GET, PUT, POST, DELETE). The client uses these verbs to make different kinds of requests to the server. The server responds to these requests by getting data on the state of its system and grabbing data and the API sends the data back to the user.
HTTP Verbs:
- GET: The GET method is used to retrieve information from the given server using a given URI. Requests using GET should only retrieve data and should have no other effect on the data.
- POST: A POST request is used to send new data to the server, for example, customer information, file upload, etc. using HTML forms.
- PUT:Replaces all the current representations of the target resource with the uploaded content.
- DELETE:Removes all the current representations of the target resource given by URI.
There are many more verbs but these four are the most commonly used ones. These verbs are similar to the terms used in database functions Create, Report, Update, Delete. Create is similar to POST where the client sends new data. Get is similar to Report where a client retrieves certain data. PUT is similar to Update where the client updates existing data in the database. And Delete is similar to Delete in CRUD where the client deletes certain data.
Status Codes
Once a server receives and processes an HTTP request, it will return an HTTP response. Included in this response is an HTTP status code. This code provides information about the results of the request. A client sending requests to the API can check the status code and perform actions based on the result. These actions could include handling errors or displaying a success message to a user. You probably see these from time to time when opening a website. The server might send “404 page not found”. This means that the requested resource was not found. Figure 3 shows the classes of HTTP Status codes. 100’s are informational. 200’s indicate a successful response. 300’s indicate a redirected request. 400’s indicate a client error. 500’s indicate a server error.
A REST API exposes a set of public URLs that client applications use to access the resources of a web service. These URLs, in the context of an API, are called endpoints. Table 1 below illustrates some endpoints of the gitHub API
| HTTP Method | API Endpoint | Description |
| GET | /customers | Get a list of customers |
| GET | /customers/<customer_id> | Get a single customer |
| POST | /customers | Create a new customer |
| PUT | /customers/<customer_id> | Update a customer |
Github REST API
Imagine if you want an emoji element in your website and GitHub builds the database for emojis. All you have to do is to make a GET request to GitHub to get emoji data.
First, we can get emojis from GitHub API by making a GET request to this URL:
In postman, create a new HTTP request and type this URL in it you will get a JSON response like this:
{
"+1": "https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png?v8",
"-1": "https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png?v8",
"100": "https://github.githubassets.com/images/icons/emoji/unicode/1f4af.png?v8",
"1234": "https://github.githubassets.com/images/icons/emoji/unicode/1f522.png?v8",
"1st_place_medal": "https://github.githubassets.com/images/icons/emoji/unicode/1f947.png?v8",
"2nd_place_medal": "https://github.githubassets.com/images/icons/emoji/unicode/1f948.png?v8",
"3rd_place_medal": "https://github.githubassets.com/images/icons/emoji/unicode/1f949.png?v8",
"8ball": "https://github.githubassets.com/images/icons/emoji/unicode/1f3b1.png?v8",
"a": "https://github.githubassets.com/images/icons/emoji/unicode/1f170.png?v8",
"ab": "https://github.githubassets.com/images/icons/emoji/unicode/1f18e.png?v8",
"abacus": "https://github.githubassets.com/images/icons/emoji/unicode/1f9ee.png?v8",
"abc": "https://github.githubassets.com/images/icons/emoji/unicode/1f524.png?v8",
"abcd": "https://github.githubassets.com/images/icons/emoji/unicode/1f521.png?v8",
"accept": "https://github.githubassets.com/images/icons/emoji/unicode/1f251.png?v8",
"accordion": "https://github.githubassets.com/images/icons/emoji/unicode/1fa97.png?v8",
"adhesive_bandage": "https://github.githubassets.com/images/icons/emoji/unicode/1fa79.png?v8",
"adult": "https://github.githubassets.com/images/icons/emoji/unicode/1f9d1.png?v8",
"aerial_tramway": "https://github.githubassets.com/images/icons/emoji/unicode/1f6a1.png?v8",
}
This GET request returns a status code 200 which means the request is successful, then returns a list of emojis’ URLs. These are just the first few rows of the JSON response. The actual response is over 1800 lines. You can also request individual emojis. For example, if you make a request to one of the URLs (https://github.githubassets.com/images/icons/emoji/unicode/1f251.png) , you get the image shown in Figure 4:
You can also do POST, DELETE, and PUT actions using GitHub API but I will not go through those here. If you are interested, check out their API action page.
Summary
REST provides a more secure and flexible software development environment for software engineers. Moreover, given that billions of devices are using modern software at the same time (Amazon, Netflix…etc), REST also satisfies user experience with faster and more reliable data access. REST provides a set of architectural constraints that, when applied as a whole, emphasizes scalability of component interactions, the generality of interfaces, independent deployment of components, and intermediary components to reduce interaction latency, enforce security, and encapsulate legacy systems.