A REST API (also called a RESTful API or RESTful web API) is an application programming interface (API) that conforms to the design principles of the representational state transfer (REST) architectural style. REST APIs provide a flexible, lightweight way to integrate applications and to connect components in microservices architectures.
REST is not a protocol or a standard, it is an architectural style. During the development phase, API developers can implement REST in a variety of ways.
Like the other architectural styles, REST also has its guiding principles and constraints. These principles must be satisfied if a service interface has to be referred to as RESTful.
How REST APIs Work
REST APIs utilize HTTP requests to execute standard database functions such as creating, reading, updating, and deleting records (referred to as CRUD operations) within a resource.
For instance, a GET request is employed to retrieve a record, while a POST request creates a new one. A PUT request updates a record, and a DELETE request removes it. All HTTP methods are applicable in API calls. A well-structured REST API closely resembles a website functioning in a web browser, equipped with built-in HTTP capabilities.
The state of a resource at any given time, or timestamp, is termed the resource representation. This data can be transmitted to a client in various formats, including JavaScript Object Notation (JSON), HTML, XML, Python, PHP, or plain text. JSON is favored for its readability by both humans and machines, and its independence from programming languages.
Request headers and parameters are integral components of REST API calls, as they contain vital identifier information such as metadata, authorizations, uniform resource identifiers (URIs), caching directives, cookies, and more. Request headers, response headers, and conventional HTTP status codes are pivotal elements within well-designed REST APIs.
The Six Rules of REST APIs
To fully benefit from the functionality that REST provides, APIs must follow six requirements. (Well, technically five are required and one is optional.) Each requirement lays the groundwork for a fast and versatile API.
1. Client-Server Separation
Under REST architecture, the client and server can only interact in one way: The client sends a request to the server, then the server sends a response back to the client. Servers cannot make requests and clients cannot respond — all interactions are initiated by the client.
By simplifying communication between clients and servers, RESTful APIs keep the two conveniently independent. This way, client software can grow their builds without worrying about affecting any other servers, and server contents can be modified without inadvertently affecting clients.
2. Uniform Interface
Applying the principle of generality to components’ interfaces simplifies the overall system architecture and enhances interaction visibility. Various architectural constraints contribute to achieving a uniform REST interface, guiding component behavior.
Four constraints ensure a uniform REST interface:
- Identification of resources: The interface must uniquely identify each resource involved in client-server interactions.
- Manipulation of resources through representations: Resources should have uniform representations in server responses. API consumers use these representations to modify the resource state on the server.
- Self-descriptive messages: Resource representations should contain sufficient information to describe message processing. They should also provide details of additional actions clients can perform on the resource.
- Hypermedia as the engine of application state: Clients should only possess the initial URI of the application. Client applications dynamically drive other resources and interactions using hyperlinks.
In simpler terms, REST establishes a consistent and uniform interface for client-server interactions. For instance, HTTP-based REST APIs utilize standard HTTP methods (GET, POST, PUT, DELETE, etc.) and URIs (Uniform Resource Identifiers) to identify resources.
3. Stateless
All calls with a REST API must be stateless. This means that every interaction is independent, and each request and response provides all the information required to complete the interaction. Every request by the client is interpreted by the server as a brand new ask — the server remembers nothing about past requests.
Stateless transfers greatly reduce the amount of server memory needed and improve the odds of a successful response, since the server is not required to take additional action to retrieve old data. This ensures that these interactions are scalable: As software grows and makes more requests, developers don’t need to worry about significantly more memory being used, or overloading the server with requests.
4. Layered System
So far I’ve described API requests as a simple interaction between a client and server, but this is a bit of a simplification. In reality, there are typically more servers between these two entities. These servers, or layers, are there to add security, handle and distribute traffic, or assist with a number of other important functions.
This principle requires that messages between the client and target server should always be formatted and processed the same way, regardless of layers that sit between them. Additional layers should not affect client-server interactions.
When developers follow this guideline, server systems can be rearranged, updated, or otherwise modified with no effect on the core request-response.
5. Cacheable
The cacheable constraint requires that a response should implicitly or explicitly label itself as cacheable or non-cacheable.
If the response is cacheable, the client application gets the right to reuse the response data later for equivalent requests and a specified period.
6. Code on Demand (Optional)
The final REST principle is optional. If desired, an API can send computer code to clients in its response. This empowers the client to run the code in its own backend.
As long as an API adheres to this set of rules, it is considered RESTful. However, these rules leave plenty of room for developers to customize the functionality of their API. This flexibility distinguishes REST APIs from another common web API method, the Simple Object Access Protocol (SOAP).