What Is a REST API?

A REST API is a type of application programming interface (API) that complies with the representational state transfer (REST) model of data representation and communication between two systems (a client and server) over a network such as the Internet. REST APIs support information exchange between internal and third-party applications, and enable businesses to integrate multiple endpoints into their application ecosystem.

Note: Strictly speaking, REST refers to the model and is not an adjective designating an API that adheres to it, for which the proper term is RESTful API. However, REST API is the more common usage and accordingly is used in this article.

What Is an API?

An API is a set of definitions, rules, and protocols that structure the data exchange between an information user (client) and information provider (server). In other words, APIs act as a communication method between users (either people or software) accessing information (data resources made available by online and web applications). When a developer creates and exposes the API for an application, it allows other applications to communicate programmatically with the application.

APIs enable businesses to make data-driven decisions by making information reusable and accessible. They also enable developers to streamline work. Rather than spending unnecessary time duplicating the functionality of an existing application, developers can integrate the functionality into their applications by making calls to functions in the existing application’s API.

To learn more about the many different ways to use APIs, see What is API Connectivity?

What Is REST?

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
• Cacheability
• 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.

What Is a Resource?

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.

Benefits of REST APIs

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.

REST APIs vs. GraphQL

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.

How Can NGINX Help?

The flexibility of REST APIs is certainly an advantage. But too much flexibility can also lead to designing a potentially slow or broken API, which is why many developers choose to publish, manage, and generate documentation of APIs using the OpenAPI Specification.

API Connectivity Manager, part of F5 NGINX Management Suite, supports the OpenAPI Specification for REST APIs. API Connectivity Manager was designed with the API developer experience at its core. It is a lightweight, cloud-native API management solution with seamless integration for publishing APIs to the developer portal and API gateway.

Start a 30-day free trial of NGINX Management Suite, which includes API Connectivity Manager and Instance Manager.