REST API — introduction

The article has been originally posted on my Polish blog — devszczepaniak.pl.

At the very beginning let’s decipher the REST acronym. REST stands for Representational State Transfer. REST is a programming architecture style that determines the way how application resources can be accessed. The following term has been introduced in 2000 by Roy Fiedling.

The next acronym is API — Application Programming Interface. API is the set of rules and tools that defines how to communicate with a system. It includes human-computer communication but also communication between systems/applications.

To sum it up briefly — API defines how to communicate with a system, and REST is an architecture style that defines the API shape.

The last acronym, inseparably related to the topic is HTTP — Hypertext Transfer Protocol. HTTP (but way more often its secure version — HTTPS) is a protocol that you use every day, also to read this article. To communicate with REST APIs, the HTTP methods are used. In general, there are nine HTTP methods, but in practice, most of APIs uses only four of them:

• GET
• POST
• PUT
• DELETE
• CONNECT
• OPTIONS
• TRACE
• PATCH
• HEAD

As I mentioned, for most of the cases the first four methods are sufficient.

How do APIs work?

The workflow with API can be described in a few points:

1. A client prepares a request for a particular address — endpoint.
2. The client sends the prepared request.
3. The system receives a request and prepares a response.
4. The response is sent back by the system to the client.
5. The client receives and processes the response.

For most of the readers, this workflow may be obvious by my goal for this article is EVERYONE, after reading this article knows what an API is and how it works.

The HTTP methods

Because it is just an introduction, I’m going to describe only four basic HTTP methods:

GET — as the name says, it is used mostly to getting data. All additional data are passed in the headers or as query params. The example request may look like http://example.com/api/resource?per_page=10&page=2. Pretty often the GET method is also used to determine whether a particular resource exists. However, in my opinion, a way more useful HTTP method for this purpose is the HEAD method. The main difference is that the HEAD method response is more lightweight and includes only headers. In this case, the only information that you need is a status code that is included in the HTTP header response (usually it is 200).

POST — this method dedicated to creating and sending data by using the request body. Note that, the POST response should return the Location header with the location of the newly created resources.

PUT — similar to the POST method. The main difference is that a PUT endpoint should point to the exact resource. PUT is mostly used to updating existing resources. Worth mentioning is the fact, that PUT overwrites the whole resource — for a partial update, the PATCH method is recommended.

DELETE — the method dedicated to deleting resources. In most of the cases, this method will return just a set of headers with status code equals 204(no content).

The REST rules

To say an API is RESTful, it needs to meet a few assumptions:

1. Separate user interface (UI) from the operations on the application server. The client application can only affect the server by sending HTTP requests. Also, the server-side part of the application cannot affect the user interface. It allows using the API in various systems, and reuse the UI for different APIs.
2. Stateless — it is said that REST is stateless. It means that every single request has to include the full set of information to process the request. There are no constructs like states, sessions, etc..
3. Cacheability — the response returned by the API has to clearly define whether it’s cacheable or not. It has a huge meaning in the case of different types of resources. Let’s say we have a system for tracking airplanes. Some information, for example, an airplane position, should not be cacheable — it changes dynamically. However, the information about the color, available seats, or the airplane name for sure should be cacheable.
4. Endpoints — the resources’ addresses — should clearly define what resources they point on. Their structure should describe the accessed resource. Also, the endpoint structure should not rely on the database structure. Of course, it may be that the endpoints may look like a database structure but for sure these parts of the system should not be dependent on each other.
5. Layers separation — data access, presentation, and business logic layers should be separated. None of the layers should have an impact on others. Moreover, the use of additional APIs used by the server-side application should be hidden. For example, the information about the airplane color may come from another API. A user doesn’t have to know about it.
6. Providing additional scripts and adapters for the API. If we know that our solution is used together with other solutions it is worth considering creating a dedicated integration app or adapter. For example, pretty often use cases are authentication mechanisms.

The advantages of using APIs

The main advantage is versatility. Let’s say you have to prepare a web application and a mobile app for an online bookstore. You can use the same API for both projects!

For the second — the truly RESTful interfaces are intuitive and using them is easy and convenient. It reduces the time spent on reading documentation.

Also, you can use resources from various APIs for a single application.

The last advantage is that there are many tools to work with APIs more convenient. One of the most popular is Postman.

The data format

APIs mostly return data in the JavaScript Object Notation (JSON) format. Sometimes, but less and less, the XML format is used. The JSON format is pretty readable and intuitive.

The examples of popular APIs

• Google Geolocation API,
• YouTube Data API,
• WordPress REST API,
• SWAPI
• and tons of other solutions!

Summary

I hope you found something useful in this short introduction to this topic.

The original source of this article is the blog post from my Polish blog. I’d like to thank Comandeer who added a supplement for this topic under the original article.