An Overview of the REST Principles

An Application Programming Interface (API) is a software component that offers a service to other pieces of software through a set of rules and functions that define how two or more computer programs can communicate with each other. Its goal is to allow resources and information to be shared while maintaining an increased level of security and control by hiding the implementation details. More broadly, it can be seen as a collection of tools that developers can use to implement functionalities without having to know the underlying mechanisms of the system it relies on.

In this sense, a web service is a type of API that makes a resource available on the internet by listening to incoming requests on a particular port and serves web documents (e.g. HTML, JSON, XML) using the World Wide Web (WWW) protocols such as HTTP and messaging protocols such as SOAP or REST.

The representational state transfer

The Representational State Transfer (REST) is a type of software architecture that defines a set of constraints or principles, designed to guide the development of network-based applications, and more specifically client-server applications. It focuses on the usage of uniform interfaces, the independent deployment of components and the creation of a layered architecture. Beyond that, the REST principles have been widely accepted by the industry as a standard for creating stateless and reliable web APIs, called RESTful APIs.

How does it work?

A RESTful API enables a client to send requests to the server in order to perform CRUD operations on the database—CRUD being an acronym for Create, Read, Update and Delete. These requests are usually sent over the network using the HTTP protocol and are mainly composed of a header, a method, and a payload.

Where:

• The header usually contains information like metadata, cookies, authorizations and so on.
• The method is a verb that defines the operation the client wishes to perform on the server, for example:
  • GET to retrieve a record
  • POST to create a record
  • PUT to update a record
  • DELETE to delete a record
• The payload contains the data the client wants to send over, like the email address and the password of a user, in the case of a login operation.

While some APIs impose a strict framework on developers, RESTful APIs can be developed using any programming language and support a variety of payload formats, the most popular being the JavaScript Object Notation (JSON) as it is readable by both humans and machines.

The REST principles

In order for a web service to have an API that’s considered RESTful, it must align with the following REST principles:

• The access to its resources should go through a uniform interface; all of the API requests for the same resource should look the same no matter which client they come from, whether it’s a browser, an Android app or a script running on a Linux server.
• The client and the server must be completely decoupled; the only thing the client should know in order to access a resource is its unified resource identifier (URI).
• The API must be stateless; each request sent by the client is considered unique and must therefore contain all of the necessary information for the server to process at once.
• Resources sent by the server must be cacheable on the client side, unless explicitly indicated, in order to improve performance so that the client doesn’t request the same data repeatedly if it is not expired.
• It must allow for a layered architecture, which means allow a request or a response to go through several layers like security, cache or load-balancing without being modified and without the client being aware of it.