What is RESTful API

If you have landed on this page, there is a high chance you want to know more about RESTful API. But before we start talking about RESTful API lets define first what is REST API? and What is the difference between REST and RESTful API?.

Related Articles:

This article will cover:

What is REST API?
What is RESTful API?
REST Architecture
Summary
You might also like:

What is REST API?

REST, stands for REpresentational State Transfer, is an architectural style that provides standards and a set of rules that systems on the web follow. This standards make the communication between systems much easier and more flexible. In the REST architectural style, data and functionality are considered resources. Resources are accessed using Uniform Resource Identifiers (URIs), so a resource could be any information: a document or image, a temporal service or a collection of other resources. When an application requests a resource using the resource identifier, the API delivers the current representation of that resource in a format that the client application can consume, such as a JPEG image, HTML page, or JSON.

What is RESTful API?

To be referred as RESTful, a REST API must satisfy the principles illustrated in the table below:

Principles	Meaning
Separation of Client and Server	That means the implementation of the client interface and the implementation of the server and data storage should be done independently without each knowing about the other. This separation will improve the portability of the front end part across multiple platforms and improve scalability by simplifying the server components.
Stateless	The server does not need to know anything about what state the client is in to understand the request and the client can understand any message received, even without seeing previous messages.
Cacheable	RESTful API requires that the data within a response to be implicitly or explicitly and should be labeled as cacheable or non-cacheable.
Uniform interface	In order to obtain a uniform interface, the resources in the system must meet these criteria: – A resource should have only one logical URI, and that should provide a way to fetch related or additional data. – Any single resource should not be too large and contain each and everything in its representation. – the resource representations should follow specific guidelines such as naming conventions, link formats, or data format (XML or/and JSON). – All resources should be accessible through a common approach such as HTTP GET and similarly modified using a consistent approach.
Layered system	REST allows the use of a layered system architecture so you can deploy the APIs on server, and store your data on a different server without letting the client Know if he is connected directly to the end server or there is an intermediary along the way.

REST Architecture

The above architecture shows the communication schema between client and server in a REST API. A request is made by the client and sent to the server in order to create, retrieve, change or delete resources. The server executes the queries related to the client request and sends a response. So let’s take a look at the standard ways to make requests and send responses.

REST Client request

Using REST principles more strictly in the web intends to make it more streamline and standard. So that allows clients and servers exchange representations of resources by using a standardized interface and protocol (typically HTTP or HTTPS for a secure communication) and enables developers to develop any kind of web application having all CRUD paradigm (Create, Retrieve, Update, Delete) operations using HTTP methods (POST, GET, PUT, PATCH, DELETE). So we can say any interface, including HTTP (or HTTPS) and honoring the principals mentioned above can be a RESTful interface.

In REST, a client request is made up of four parts:

HTTP method: The method provides the meaning for the request you send to the server and define what operation to perform. HTTP has five types of method that you can use in your API:

Method	Meaning and operation to perform
GET	Retrieves a specific resource (or a collection of resources) without making any change to the resource state.
POST	This method is used to create a new resource into the collection of resources.
PUT	Updates or replaces a specific existing resource identified by the request URI.
PATCH	Makes a partial update or a small correction on an existing resource (note that : not all browsers support PATCH method).
DELETE	Is used to delete a specific resource.

Header: Headers are used to pass informations sent by the client to server. It can be used for authentication and providing information about the body content such as content-type to ensure that the server will not send data that cannot be understood by the client (note that JSON is the common format for sending and requesting data through a REST API). An HTTP request could have different headers under the form of property-value pairs separated by a colon.

Path: The path contains the information necessary to determine the resource you are requesting. For example, lets say the starting point for your API is: “https://yourAPIDomaineName.com” and you want to get and retrieve an employee with a specific id, so you navigate to “https://yourAPIDomaineName.com/employees/:id”, the path to the resource, in this case, is “/employees/: id”.
Body: This option is only used with HTTP methods and contains data or message.

REST Server response

Responses from the server contain a content types and a response code.

Content type

The content-type is included in response header when the server is sending back data to the client. The type of the content in the response should be one of the options that the client specified in the content-type of request header .

Response code

Responses status codes are used to alert and inform the client about the success of the operation. the table below represents the HTTP methods and their expected status codes and how they are used:

HTTP Method	Meaning	Status code	Response body
GET	Retrieves a specific resource or a collection of resources	200 (OK): if the resource is found. 404 (NOT FOUND): if the resource not found. 400 (BAD REQUEST): if the request is not correctly formed.	YES: XML or JSON content
POST	Create a new resource	201 (CREATED) 200 (OK) or 204 (NO CONTENT): Response for successful POST, where nothing is being returned in the response body. 400 (BAD REQUEST): if the request is not correctly formed.	YES: XML or JSON content with the status code 201
PUT	Update a specific existing resource	201 (CREATED): if the resource does not exist and a new one has been created by the PUT. 200 (OK) or 204 (NO CONTENT): Response for successful PUT, where nothing is being returned in the response body. 400 (BAD REQUEST): if the request is not correctly formed.	YES: XML or JSON content with the status code 201
DELETE	Delete a specific resource	200 (OK): if the response includes an entity describing the status. `202(ACCEPTED`: if the action has been queued. 204 (NO CONTENT): Response for successful PUT, where nothing is being returned in the response body. 404 (NOT FOUND): if the resource was already removed.	NO

Summary

In this article, we answered the questions of what is a REST API and what we call RESTful API. Also, we explained the REST API architecture and gave you the structure of a client request and server response. Hope the table summary was a help to learn more about HTTP methods and responses status codes.

To see a real practice of all the knowledge learnt in this article click here: Building a complete RESTful API with node.js.