REST API has emerged as a common method for connecting components and applications because it provides flexibility and freedom for developers. Computer Scientist Dr Roy Fielding was the first to define APIs in his Ph.D. dissertation. This article talks about what a REST API is, its features and characteristics and also briefly discusses how it differs from other architectures.

What's an API?

API
An API (Application Programming Interface) is a mechanism that enables service or an application to access a resource within another service or application. APIs are structured in the sense that they are defined by an industry standard, and there are a few popular formats such as REST, SOAP, and GraphQL.

What exactly are REST APIs?

REST API is an API(Application Programming Interface) that conforms to the REST architectures. REST is an acronym for REpresentational State Transfer which is an architecture style for building resources on the web. It defines a pattern for client-server communications. For this reason, REST APIs are sometimes known as RESTful APIs.

A resource in REST is an abstraction of information. Anything can be described as a resource, be it a document, an image, a collection of other resources or even a non-virtual object such as a person. The application requesting a resource is known as a client and the application containing the resource is called a server. The REST API’s resources can be accessed by a URI. URI is a Uniform Resource Identifier that describes the network location of the resource and identifies the resource to retrieve or update.

REST HTTP Methods

A method is a type of request you send to the server. Below are some of the methods:

GET

It is used to retrieve or read information from the server. GET requests are only used to read resources and not change them. When used this way, they are considered safe since there is no risk of data modification or corruption. They are idempotent that calling it once has the same effect as calling it 20 times.

POST

It is utilised to create new subordinate resources. POST is not safe or idempotent. Therefore making two identical POST requests will result in two resources containing the same information.

PUT

The PUT method replaces all current representations of the target resource with the request payload. It is not a safe operation since it modifies or creates resources on the server. It is idempotent in that if you create or update a resource using PUT and then make the same call again, the resource is still there and has the same state as it did during the first call.

PATCH

The PATCH method is used to apply partial modifications to a resource. PATCH is neither safe nor idempotent. However, a PATCH request can be issued in such a way as to be idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame.

DELETE

It is used to delete a resource from the server. This request is idempotent, repeatedly calling DELETE on a resource ends up the same since the resource no longer exists.

CONNECT

The client uses the CONNECT method to establish a network connection to a network server over HTTP.

OPTIONS

The client uses this method to find out the HTTP methods and options that are supported by a web server.

TRACE

The TRACE method performs a message loop-back test along the path to the target resource, which can be used for debugging during development.

RESTful web services.

A web service is a service exposed over the web to perform a certain function. For an API to be considered RESTful, it has to conform to these criteria:

What characterizes a Restful API?

Client-Server architecture

REST services must be based on a client-server architecture. It contains clients, servers and resources.
Statelessness

No client information between get requests and each request is separate and unconnected.
Cache-enabled information

To improve network traffic efficiency, responses or answers from the server have to be cache enabled. This information is used by REST clients to decide whether to perform a local copy of the resource.
Uniform Interface

Uniform Interface streamlines the whole system architecture and enhances the visibility of communications. This is attained by several architectural controls that guide the performance of the elements within the REST API architecture.
Layered System

To generate more scalable and flexible applications, REST API includes several layers that operate together to construct a hierarchy.
Resource access by name

A REST system is made of resources accessed via URL, and these must be intuitive, predictive and easy to understand and set. A way to achieve this is by employing a hierarchical structure, similar to directories. The access to resources is made as a composition of an URL that identifies the resource and must be the same even if the implementation on the server is modified.
Explicit use of HTTP methods.

To access resources, REST services use HTTP methods such as GET, PUT, PATCH, POST and DELETE.
Use of lightweight data models

Whenever a client requests a resource, the answer resource must be simple and understandable by humans and translatable by an application. The most common known answer formats are JSON (JavaScript Object Notation), XML(Extensible Markup Language) and CSV (Comma Separated Values).

How does it differ from SOAP API

SOAP is a standard communication protocol system that permits processes using different operating systems like Linux and Windows to communicate via HTTP and its XML.

It differs from REST API in the following ways:

SOAP has a standard since it's a protocol but REST doesn’t because it’s an architectural style.
SOAP is largely based on HTTP and XML alone while REST supports HTTP,XML,JSON and URL.
SOAP API uses Web Services Description Language to describe services offered by Web Services while REST uses Web Application Description Language.

API LIFECYCLE

Just like when we are creating software we follow the Software Development Life Cycle, when we are building APIs, we follow an API lifecycle.

API lifecycle

Creating APIs

It involves:

Developing the API definition and implementation.
Writing the API definition and implementation.
Debugging the API.
Submitting the API.
Testing the API.

Running APIs

This stage involves:

Staging the API.
Packaging the API.
Publishing the API.

Managing APIs

This stage involves:

A set of rules: where, how and with whom the API is shared.
Retiring and archiving the API.
Tracking its performance and seeing if it meets its stated purpose.

Monitoring APIs

This stage involves:

Securing APIs.
Access control.
Monitoring the API.
Logging.

CONCLUSION

In this article, you learned about REST APIs, their properties, HTTP methods, how they differ from SOAP APIs, and how an API's lifecycle works. Keep in mind that APIs expose business capabilities and services, thus if the API isn't properly created, it might cause issues not only in the API application but also in the application's calling. I hope you've learned enough about REST APIs from this article to be able to use them confidently in your projects. If you have a query, feel free to leave a comment.

What exactly is REST API, and how does it differ from other architectures?