What Is a REST API?

REST, which as mentioned stands for representational state transfer, is an architectural style created by computer scientist Roy Fielding in 2000. REST provides flexibility for developers, which makes it ideal for connecting applications in microservices architectures.

REST defines six constraints which apps and APIs must obey to be considered RESTful:

• Uniform interface
• Client-server architecture
• Statelessness
• Layered system
• Cacheabilit
• Code-on-demand

You can learn more about these constraints at Wikipedia.

Uniform Interface

A uniform interface simplifies the overall system architecture and improves interaction visibility. It also has specific requirements to ensure that information is being transferred in a standard form.

Four constraints enable a REST interface to be uniform:

• Each resource has a unique identifier such as a URI, and the representation of the resource in a message is separate from the server’s internal representation
• The resource representation includes enough information for the client to modify or delete a resource’s state
• Each message includes enough information to describe how to process it
• The server uses hyperlinks to inform clients about available resources, eliminating the need for clients to know about server internals

Client-Server

A client-server architecture is comprised of clients, servers, and resources. Separating the user interface (controlled by the client) from data storage (controlled by the server) means client and server components can evolve autonomously. It also simplifies the portability of the client user interface across multiple platforms and the scalability of the server.

On the Internet, client-server interaction takes place over HTTP.

Statelessness

In client-server communication, statelessness means the server doesn’t store any information about the client or the session established with it. The client’s representation of session-related information in each message must enable the server to understand it in isolation, without any context from previous messages. This reduces server load, improving the performance of high-volume applications.

Layered System

Clients do not need to know (and usually cannot tell) whether they are connected directly to the server or to an intermediary like a reverse proxy or load balancer. Intermediary servers help improve scalability and can be used to handle security so that servers are responsible only for business logic.

Cacheability

HTTP clients and intermediaries can cache server responses to reduce load on the server and increase the speed of data delivery to end users. The server must indicate whether a response is cacheable or non-cacheable, with the latter ensuring that responses to subsequent end-user requests are correct and up-to-date (not potentially “stale”). Because clients access a resource by its URL, which is a unique identifier, the client can determine what to cache at the resource level.

Code-on-Demand

Code-on-demand means the server can send executable code to temporarily extend or customize client functionality, eliminating the need for the client to implement the functionality itself. The code-on-demand constraint is optional.

The most important data representation or abstraction in REST is a resource. A REST resource can be any type of abstracted information – from a digital document to a non-digital object. The state of the resource at any given time is called the resource representation.

A resource representation has three parts:

• Data
• Metadata
• Hypermedia links

A REST API consists of an assembly of interlinked resources (or its resource model ) that are accessible at unique URIs. A client can achieve flexible functionality by linking to related resources and URIs within the response. In general, a request to a REST API is sent in the form of an HTTP GET request; servers often format their responses as JSON.

The following HTTP request methods are used to act on resources in the indicated way:

• GET – Load a resource
• POST – Create a new resource
• PUT – Modify an existing resource
• DELETE – Remove a resource

Resource Identifier

In REST architectural styles, resource identifiers uniquely designate each resource that’s involved in client-server interactions.

Hypermedia

A “media type,” or representation of data format, defines how a resource should be processed. In REST APIs, all media types are based on JSON and are hypermedia (sometimes known as, thought slightly different from, hypertext). Hypermedia is any piece of content with links to other media. Hypermedia as the Engine of Application State (HATEOAS) is what makes the REST architecture unique.

Note: According to Roy Fielding, for an API to be considered a REST API, it must use hypermedia. However, many API designers today often call their APIs “REST[ful]” as a buzzword even though they don’t use hypermedia/hypertext.

Self-Descriptive

Resource representations aim to be self-descriptive, meaning the API makes itself understood within its own context. With self-descriptive representations, the client doesn’t need to know what category a resource belongs to and instead acts based on the media type associated with the resource.

Today, most businesses use internally developed and third-party APIs for communication among apps which provide basic, innovative, and critical functionality. The majority of these APIs are REST APIs, because the specific communication standards mandated by REST enable secure, efficient, and reliable information exchange. REST APIs can also work with any protocol.

REST APIs are also secure because the RESTful web service authenticates requests before a response is sent. To verify user identities, REST APIs employ HTTP authentication (both Basic and Bearer Token), API keys, and OAuth for login access.

Other benefits of REST APIs include:

• System scalability – REST APIs can scale efficiently because REST optimizes interactions between client and server. The RESTful statelessness constraint reduces server load because the server doesn’t have to save information from or about previous requests. Additionally, cacheability reduces the number of client-server interactions that could potentially create bottlenecks. This results in scalable, high-performance APIs.
• Flexibility for developers – Many enterprise applications need to communicate with internal or third-party APIs. RESTful web services support separation between client and server, which enables each to evolve independently.
• Technological independence – REST APIs remain independent of the programming language and framework in which the corresponding apps are developed. Client and server apps don’t need to share a language or framework, and those can change without affecting the API design or the communication process.

While REST remains the most popular architecture for connecting client and server applications, GraphQL (developed by Facebook in 2012 and open sourced in 2015) was designed as an alternative to REST. GraphQL APIs are more efficient than REST APIs because all data that’s needed is requested in a single request and in a standardized form, but there are still some areas where REST shines. GraphQL requires a steep learning curve and is far less cacheable than REST. Additionally, applications are often driven by resources and don’t require a query language like GraphQL. That said, each model has its pros and cons and organizations can choose to use both.