An API provides an interface through which applications communicate. There are different ways to organize that communication, and REST is one of them.
A practical way to understand REST APIs is to follow a real workflow. Let us explore how listing products, creating a product, and changing its price work in a product catalog.
What Is a REST API?
REST stands for Representational State Transfer. It is an architectural style for communication in distributed systems. A REST API is an application interface based on that approach.
The central concept in REST is the resource. A product, user, order, or article can be a resource. On the web, resources are identified by addresses and generally operated on using HTTP methods.
For example, a product might have this address:
https://api.example.com/products/42This address identifies the product with the ID 42. Instead of creating separate addresses for reading, updating, and deleting it, the client can send different HTTP methods to the same resource address.
Resources and Representations
A resource is not the same as the representation sent through an API. The resource is the product in the system. Its representation is a form that can be transferred to a client.
The server may store a product's description, supplier details, cost, and inventory history. A public API might expose only these fields:
{
"id": 42,
"name": "Wireless Mouse",
"price": 25,
"currency": "USD",
"stock": 18
}This JSON object is a representation of the product. It does not have to expose every database field or the structure of the underlying table.
JSON is common in REST APIs, but it is not required. An API can support other representation formats.
What Does a REST Request Contain?
To understand a REST request sent over HTTP, consider four parts together:
- Address: Identifies the target resource.
- HTTP method: Expresses the intended operation.
- Headers: Carry additional information, such as data format preferences and authentication credentials.
- Request body: Contains data submitted for the operation. Not every request needs a body.
The server response contains a status code, response headers, and a response body when appropriate. Let us see how these parts work in the product catalog.
Retrieving a Product with GET
To read a product's details, the client sends a GET request:
GET /products/42 HTTP/1.1
Host: api.example.com
Accept: application/jsonThe Accept header indicates that the client wants a JSON response. If the request succeeds, the server might return:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Wireless Mouse",
"price": 25,
"currency": "USD",
"stock": 18
}200 OK indicates success. The Content-Type header identifies the response body's format.
If the product does not exist, the server may return 404 Not Found. GET is intended for reading data, so it should not be used to delete products or change prices.
Creating a Product with POST
A new product can be created by sending a POST request to the product collection:
POST /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json
{
"name": "Mechanical Keyboard",
"price": 80,
"currency": "USD",
"stock": 10
}The product details are included in the request body. After validating the request and creating the product, the server could respond:
HTTP/1.1 201 Created
Location: /products/43
Content-Type: application/json
{
"id": 43,
"name": "Mechanical Keyboard",
"price": 80,
"currency": "USD",
"stock": 10
}201 Created indicates that a new resource was created. The Location header identifies its address.
POST is not limited to creating records. However, adding a resource to a collection is a common use in REST-based APIs.
Updating a Product with PUT and PATCH
Both PUT and PATCH can be used for updates, but they have different meanings.
PUT: Replacing a Resource Representation
PUT replaces the target resource's representation with the submitted content. The client is expected to send the complete writable representation defined by the API:
PUT /products/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "Wireless Mouse",
"price": 30,
"currency": "USD",
"stock": 18
}A complete representation does not mean every column in the database. Required fields depend on the API contract. Server-generated fields, such as an identifier or creation timestamp, may be excluded.
PATCH: Applying a Partial Change
If only the product's price needs to change, the client can use PATCH:
PATCH /products/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"price": 30
}This example assumes that the API supports a JSON object that updates the supplied fields. PATCH can also use other document formats. The API documentation must explain the accepted format and how changes are applied.
PUT expresses replacement of a resource representation, while PATCH applies partial modifications.
Deleting a Product with DELETE
To remove the product, the client sends a DELETE request to its address:
DELETE /products/42 HTTP/1.1
Host: api.example.comIf the operation is complete and the server will not send a response body, it can return:
HTTP/1.1 204 No ContentThe application might permanently delete the database record or mark it as inactive according to its rules. The important point for the client is that the removal behavior is clearly defined.
What Happens When a Request Is Repeated?
If a network connection fails, the client may not know whether its request reached the server. The consequences of retrying then become important.
An operation is idempotent when repeating an identical request has the same intended effect on the server as making it once.
- GET: Reads a resource; its intended operation does not change data.
- PUT: Repeatedly submitting the same representation leaves the intended resource state unchanged.
- DELETE: Repeated requests do not keep deleting the resource; the intended result is that it has been removed.
- POST: Repeated requests may create multiple records.
- PATCH: The effect of repetition depends on the modification; not every PATCH operation is idempotent.
Idempotency does not require identical response codes. The first DELETE request might succeed, while a later request reports that the resource no longer exists.
What Does Stateless Communication Mean?
One of REST's core constraints is stateless communication. Each request must carry the information needed for the server to understand and process it.
For example, a client can include access credentials with every request to a protected product management API:
PATCH /products/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"price": 30
}The server does not need to remember which screen the client previously opened or which product it selected in an earlier request. The resource address, access credentials, and requested change are included in this request.
Statelessness does not prohibit databases or persistent resource data. Using a token also does not automatically make an API stateless. The key is avoiding dependence on a previously stored conversation or session context.
How Does Caching Work in REST APIs?
If product details do not change every second, regenerating the same response for every request may be unnecessary. Suitable responses can be cached according to explicit rules.
A public product response might include:
Cache-Control: public, max-age=60This header allows appropriate caches to consider the response fresh for 60 seconds. The duration should reflect the application's freshness requirements.
Personal or sensitive responses should not be made available to shared caches in the same way. Caching rules must account for the data and its access model.
Is Every HTTP API a REST API?
Using HTTP, returning JSON, and accepting GET or POST requests does not mean that an API follows every REST constraint.
REST defines constraints including client–server separation, statelessness, caching, a uniform interface, and a layered system. An optional constraint allows executable code to be sent to the client.
The uniform interface also includes allowing clients to discover related resources and possible next actions through response links. This approach is known as HATEOAS.
A product response might include links to its own details or related resources. However, adding a few links does not establish full REST compliance. In everyday usage, the term “REST API” is also applied to resource-oriented HTTP APIs that implement only some of these constraints.
Advantages and Limitations of REST
A consistent structure built around resource addresses and HTTP methods makes an API easier to understand. The same API can support web and mobile applications written in different languages.
Stateless requests can make it easier to distribute work across servers in a suitable infrastructure. Caching can also reduce the cost of repeated reads.
However, an application may need several resource requests to populate one screen. Features requiring continuous communication, such as live chat or online games, may use other approaches, including WebSocket. REST does not have to handle every communication requirement in an application.
Conclusion
REST APIs are built around identifying resources through addresses and communicating through their representations. A product can keep the same address while being read with GET, changed with PUT or PATCH, and removed with DELETE.
Understanding REST requires more than learning method names. Request information, retry behavior, caching rules, and the responsibilities of clients and servers must be considered together.