In our last article, we discussed what is REST and the various constraints that should be adhered to by a RESTful application. All our knowledge gathered regarding the REST architecture can be applied in performing operations with REST API. In this article, we will cover the same with the following topics in the highlight.
- What is REST API?
- Why use REST API?
- Methods of REST API
What is REST API?
An API (Application Programming Interface) conforming to the REST architectural style or REST standards is known as a "REST API". A Rest API facilitates interaction between the client and RESTful web services*( server)* to get the required information. They can be used for a variety of purposes by interacting with the system. These may include specific actions such as retrieving the location of a particular city or data updation such as registering a new user. API developers use REST standards in a variety of ways to develop REST APIs. The following diagram shows a general REST API functionality.
As shown in the above diagram, REST API sits in the middle layer to the database and the presentation layer i.e. the interactive systems. The other applications (shown as the top layer) will call the REST API that has centralized core logic in one place. The applications call REST APIs to access the desired data. For example, if we try to hard code everything, we need to code for each action on the website. Retrieving book by book serial number is an action that may need to run through the middle layer and then the database. It can take a lot of time depending on the size of the database and website. With RESTful APIs, the process becomes much faster as they are lightweight. So instead of writing separate code and logic for each application, we write REST APIs accessible by any application.
What happens when a client makes a request through the RESTful API?
When a client makes a specific request, RESTful API transfers a state representation of the resource to the requester or endpoint. The format of this representation is one of several formats like HTTP: JSON (Javascript Object Notation), HTML, XLT, Python, PHP, or plain text. The most popular format generally used nowadays is JSON since it is easy to read and is very lightweight.
Headers and parameters also play an important role in the HTTP methods of a RESTful API HTTP request. They contain important identifier information regarding the request's uniform resource identifier (URI), metadata, authorization, caching, cookies, etc. These request and response headers have their own HTTP connection and status code information.
Next, let us move on to why we use REST APIs.
Why use REST API?
We mainly use REST API for the following reasons:
- As we have discussed earlier, the REST API creates an object and transmits the object values in response to the client's request. The REST API breaks down this transaction into smaller modules wherein each module addresses a specific part of the transaction. This breaking down of transactions into smaller modules requires lots of effort but also provides more flexibility for the user.
- The REST API has strict criteria to conform to. We have already seen the guiding principles (constraints) for an application to be RESTAssured in our earlier tutorials of What is REST and Rest Architectural Element. This strict adherence results in efficient REST APIs after their development. Also, we can implement this set of guidelines as needed.
- The REST APIs are considered easier than other protocols like SOAP (Simple Object Access Protocol) that have more specific requirements like built-in security, transaction compliance, XML messaging, etc. All these requirements make these protocols slower and heavier.
- The REST applications (and APIs) are more lightweight, have increased scalability, and are more suited for IoT (Internet Of Things) and mobile app development.
Methods of RESTful API
We perform CRUD Operations when we are working with web technologies and applications. As shown in the below figure, CRUD stands for Create, Read, Update, Delete. This means using CRUD operations, we can create, read, update and delete a resource. Generally, we make use of HTTP methods to perform CRUD operations. In the case of REST API methods, the REST provides these four methods in the form of APIs. Refer to the figure below:
As shown above, POST, GET, PUT and DELETE are the HTTP methods used for CRUD operations. The following table shows the description of each of these methods as well as an example URL using the swagger tool https://demoqa.com/swagger/
| HTTP Method | Operation | Operation Type | Example URL |
|---|---|---|---|
| GET | Get the list of books | Read Only | curl -X GET "https://demoqa.com/BookStore/v1/Books" -H "accept: application/json" |
| POST | Add list of books | Non-Idempotent | curl -X POST "https://demoqa.com/BookStore/v1/Books" -H "accept: application/json" -H "Content-Type: application/json" -d "{ "userId": "toolsqa_test", "collectionOfIsbns": [ { "isbn": "9781449325862" } ]}" |
| PUT | Replace ISBN object with given ISBN | N/A | curl -X PUT "https://demoqa.com/BookStore/v1/Books/9781449325889" -H "accept: application/json" -H "Content-Type: application/json" -d "{ "userId": "toolsqa_test", "isbn": "9781449325862"}" |
| DELETE | Delete book with given ISBN | Idempotent: Same results irrespective of how many times the operation is invoked. | curl -X DELETE "https://demoqa.com/BookStore/v1/Book" -H "accept: application/json" -H "Content-Type: application/json" -d "{ "isbn": "9781449325862", "userId": "toolsqa_test"}" |
How to test GET operation using REST APIs?
So how do we test these methods in a Swagger tool? Let us see an example of GET operation. Navigate to the following link: https://demoqa.com/swagger/#/BookStore/BookStoreV1BooksGet
We can see the following REST API for GET book details.
Now let us "execute" the GET operation that "gets book details". When we click this button and execute the API, the below-given command or GET syntax gets executed:
curl -X GET "https://demoqa.com/BookStore/v1/Books" -H "accept: application/json"
On performing the above operation we get the following response.
In a similar manner, we can perform other operations as well for which we have crafted dedicated posts. In subsequent articles, we will learn to create a REST API ourselves.
So here are some of the points we should remember for REST API methods.
- GET methods are read-only and safe.
- PUT and DELETE methods are idempotent: the response they return is always the same irrespective of the times the methods are invoked.
- PUT and POST operation are generally the same except for one difference that POST operation can return different results whereas PUT is idempotent.
Key TakeAways
In this article, we have given the general idea of a REST API.
- A set of APIs conforming to the REST standards and fulfilling all its constraints is REST API.
- Using RESTful API, an application can access the information from data sources like Databases using the REST API methods discussed above.
- The RESTful API is accessible by different types of applications like a dynamic web app, Android app, or desktop application. The REST API contains a core logic implemented and we need not rewrite it every time a new application enters the environment.
In subsequent articles, we will dig into more REST architecture and APIs.
