REST API
The amount of different APIs existent in the Development Business is tremendous. We as developers have to always think and analyze which ones to use, given our current demands and plans which one will be the best, the fastest, the most secured or even the one that gives us the flexibility to our daily life.
That is why at R:TI we try to explain some and showcase them in our mentoring classes and training sessions. With those learnings in mind, we are going to write this document explaining briefly one of the APIs used in our Radien application, the REST API. Why? Because RESTful web services are lightweight, highly scalable and maintainable.
?
Introduction
REST or REpresentational State Transfer is an application interface that allows interaction with RESTful web services in the most simple and flexible way possible. They can create new data, change it, get media, and much more throughout web URLs by sending a request from a client to a server.
?
Explanation
In a REST API architecture there are five HTTP methods that can be used. Each one of them will have his own specific action which we will explain.
GET: Used for read operations where the method will retrieve a representation of an object.
POST: Used to request the creation of new entries in the database.
PUT: Method that will update an already existent record, normally used to update a complete record
PATCH: Similar to PUT method PATCH is used to update a resource, but instead of replacing the complete information we normally use this to update a single information inside the record. This can only be done to records that are already existent.
DELETE: If you need to erase a record from the database the following method must be the one requested.
There are other methods such as OPTIONS and HEAD but for the moment we will be focused in the most frequent ones as explained before. If you want to learn more about the other existent methods I would advise reading the document HTTP request methods - HTTP | MDN.
To give a more practical example of the previous explanations we will go through the five most common methods assuming as an example that we have an application that stores user information (https://www.radien/api/users).
?
For a simple context information each REST request can be attached with parameters. Request parameters are used to send additional information to the server. Some of the most commonly used are:
Query Parameter: Query parameters are appended to the end of the request URL, following '?' and listed in key-value pairs, separated by '&' Syntax.
Path Parameters: These are part of the request URL.
Header Parameters: Parameters included in the request header, normally contains client side information.
?
First of all we should create a new user using the POST request as such as:
POST:/api/users
Message body: {"name":"Bruno", "age":33}
As a result we expect that our application replies us with a 200 HTTP code (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status), but to make sure our information went successfully we are going to request the information we just created.
GET:/api/users
JSON Response: {"id":1, "name":"Bruno", "age":33}
领英推荐
After checking the returned information we can see that our user information has an error so we would need to update it. In this case we could use a PUT or PATCH method, since we only need to change the age of the user we will use a PATCH as follows.
PATCH:/api/users/1
Message body: {"age":30}
?
To see what changes were affected we can retrieve again our record the same way as before
GET:/api/users
JSON Response: {"id":1, "name":"Bruno", "age":30}
?
As an example for our last missing method to delete the record we can request the same way as the others but now requesting it to delete the specific record.
DELETE: /api/users/1
Response: 200
Architecture Standards to follow.
As we've seen in our previous example a REST application only needs to consist of a client that can request for resources and a server that has those same resources and methods well defined.
Well, since we can have separation between the client and the server applications we can increase the scalability of the application without much effort, and we can migrate and have ongoing changes in our database, giving us flexibility in our daily life, but for that is advised to follow the industry standards as much as possible to ease the development and maintainability.
There are 4 main constraints that are advisable to follow.
?
Things to remember
REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers?(URIs).
The resources are acted upon by using a set of simple, well-defined operations.
The clients and servers exchange representations of resources by using a standardized interface and protocol. Typically HTTP is the most used protocol.
Every interaction with the server must be stateless.
This principles help out for RESTful applications to be simple, lightweight, and fast.
?
Conclusion
At the end REST is a simple design option to consider when thinking or planning an API, it can ease a lot of small projects growing in regards of stability or with the correct authentication increase the security of the application.
We hope you’ve learned something and can bring more ideas into your job/project discussions, just don’t stop learning and reading new ideas, projects and APIs.