REST API is short for RESTful API. REST is short for Representational State Transfer and is a style of architecture for designing networked applications: apps that use a form of network to communicate.
A REST API is your bread and butter if you build a web-based API: it’s the most common tool to use. REST defines specifications of the API through a set of rules that need to be followed when a REST API is created.
REST API characteristics
The biggest characteristic of a REST API is that it treats any data (images, video’s, texts, etc.) as a resource that the client can fetch, edit and/or delete. REST requires a client to perform a suitable operation by accessing a specific URL (Uniform Resource Locator) and sending a request. The server sends an appropriate response after that.
You can see it as a commitment (a set of rules) between the programs: the requester (the client) and the responder (the server). If the client sends “A” to the responder, the responder will give the requester “B”. A and B are specified in the commitment between the two parties and are explained in the documentation (certification) for the API.
It is key that you should be able to get a piece of data (resource) with this set of rules when you link with a specific URL.
REST is without a fixed state. This means that each request from the client to the server has to contain all the required information for the server to understand the request that is being sent. It is also tricky to build a REST API: if a REST API contains programming mistakes, everything will fall apart because the server doesn’t understand the request. The more complex the REST API, the bigger the challenge to successfully communicate with the server.
How are REST API’s used?
If you would like to get more information about a specific music artist, Google is your friend. You get onto Google and insert the music title you want information about. After hitting “enter” a list appears with articles related to this specific music artist.
A REST API works the same: you search for something and you get a list of results back from the service you are requesting from. This search is done by sending HTTP requests with a REST API and you can choose from these five types (DGPPP):
- DELETE (Delete)
- GET (Read/Retrieve)
- PUT (Create/Replace)
- PATCH (Create/Update)
- POST (Create/Update)
If you communicate with REST API’s based on HTTP requests, most of the time, it’s returned in JSON format or XML format.
JSON stands for JavaScript Object Notation and it is a way of representing data-independent from a Platform.
XML stands for Extensible Markup Language. It’s (like the name says) a markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable.
A practical example of using a REST API
To understand the use of the REST API commands, a friend advised me to check out https://petstore.swagger.io/. This site runs a sample Petstore server and can generate an interactive console that makes it easy to learn and use new APIs. It can also auto-generate documentation from comments inside of the code. It allows new users (like me) to try its UI by emulating what an API could look like for a pet store.
I started with the “POST” request. The “POST” method for the pet endpoint (the URL where the resource is hosted) can be used to create a new pet on the server. First I created an ID. I chose a random 5 digit number: 17350. Additionally, I added a pet name: Tom and as content type, I selected JSON format. After that I pressed “Execute” and the full API code was generated:
The above code exists out of 3 key components:
- The “call” which is the method “POST” and the URL of the database: https://petstore.swagger.io/v2/pet
- The header, which is:
- accept: application/json
- Content-type: application/json
- The “body”:
By running this I got the following server response with a code 200 which means that the request was successfully received:
The next request I wanted to simulate was the “GET” request. The “GET” method allows you to retrieve an item from the database. For this, I used the same ID that I used in simulating the creation of a new pet in the database: 17350 and I pressed “Execute”. The “GET” command is much shorter than the “POST” command. It exists of only one command and one header:
By running this I got the following server response with a code 200 which means that the request was successfully received:
After running this simulation, I wanted to simulate the “PUT” method. This method can be used to create/replace an existing item in the database. In this case, I updated a part of the Pet ID. I decided to change the name “Tom” (ID: 17350) into the name “Tim”. After that I pressed “Execute” and the full API code was generated:
The above code exists out of 3 key components:
- The “call” which is the method “PUT” and the URL of the database: https://petstore.swagger.io/v2/pet
- The header, which is:
- accept: application/json
- Content-type: application/json
- The “body”:
By running this I got a server response with a code 200 (successfully received):
The last command, available on the Swagger pet store server is the “DELETE” command. I used this command to simulate the removal/deletion of my created pet (ID: 17350) from the database. Like the “GET” command, it exists of only one command and one header:
By running this I got the following server response with a code 200 which means that the request was successfully received:
Now that I deleted the pet I created, I tested if it truly disappeared by using the “GET” command again:
I got the HTTP code 404: not found. This is correct because I deleted the ID from the database.
So this is how you interact with a database/server, using a REST API with the commands DELETE, GET, POST and PUT commands. The Swagger pet store has more database items to simulate with these commands as well: not only the creation, adjustment and deletion of a pet. It also has simulations in store/inventory management and user management.
Put vs Patch
If you paid very close attention, you probably noticed that the simulation lacks the PATCH command. This is because “PUT” and “PATCH” can both be used to update an item. However, it’s not the same.
PUT updates the full resource. It’s very similar in style to the POST command. PUT overwrites the entire entity if it already exists and creates a new resource if it doesn’t exist. For example, if you want to change the name of the pet in the database, you need to send the entire resource when making a PUT request, as you could see in the simulation I did. Unlike PUT, PATCH applies a partial update to the resource.
Final thoughts
I had a lot of fun researching the basics of the techniques behind a REST API. Of course, the theory and a simulation is great but it should be put into practice someday. How cool would it be to build an app myself that collects data and provides information someone can use with pushing a few buttons. I’m looking forward to that day.
Feel free to contact me if you have any questions or if you have any additional advice/tips about this subject. If you want to keep in the loop if I upload a new post, don’t forget to subscribe to receive a notification by email.
