KAHIBARO
Discord Login Register ☰
☰

7.2. What Is REST?

Table of Contents

Understanding REST

REST is a way to design and build web APIs that is simple, predictable, and easy to use. You will use REST ideas all the time as a backend developer, especially when building HTTP APIs.

This chapter explains what REST is, what it is not, and the key ideas you need before you design any REST API.

REST as an Architectural Style

REST stands for Representational State Transfer. It is not a protocol and not a library. REST is an architectural style for designing networked applications, especially APIs over HTTP.

An architectural style is a set of rules and constraints that guide how you structure and connect different parts of a system. REST says:

You can build a REST API in any language or framework, as long as you follow these ideas.

REST is an architectural style, not a standard or protocol.

If someone says "Our API is RESTful," they mean "We try to follow REST ideas."

REST and HTTP

REST works very naturally with HTTP, which you already saw in earlier chapters.

Key points about using HTTP in a RESTful way:

REST does not change HTTP. It simply says: use HTTP as it was intended, instead of inventing your own "action" mechanisms.

Bad, non RESTful idea:

http 
POST /doAction
{
  "action": "createUser",
  "data": { "name": "Alice" }
}

Better, more RESTful approach:

http 
POST /users
{
  "name": "Alice"
}

Here the resource is /users and the HTTP method POST already means "create something."

The Core REST Constraints

REST is defined by a small set of constraints. If you respect them, your API is more likely to be simple, scalable, and cacheable.

The main REST constraints are:

  1. Client Server
  2. Stateless
  3. Cacheable
  4. Uniform Interface
  5. Layered System
  6. (Optional) Code on Demand

We will focus on the ones that matter most for web APIs you will build.

1. Client Server

The client and server are separate. They communicate over HTTP, but they do not need to know each other's internal details.

This separation:

Example:

2. Stateless

Stateless means that each request from a client to a server must contain all the information needed to understand and process the request. The server does not store client session data between requests.

In practice:

Non stateless approach:

  1. Client: POST /login with credentials
    Server: "OK, you are user 123" and stores session in memory.
  2. Client: GET /profile without any ID or token
    Server: Uses in memory session to know that this is user 123.

More stateless approach:

  1. Client: POST /login with credentials
    Server: returns a token that represents the user.
  2. Client: GET /profile with header Authorization: Bearer <token>
    Server: Reads token, identifies user, and returns profile. No in memory session is required.

RESTful APIs are stateless. Every request must contain all information required to handle it.

Stateless design helps with:

Note: Many real systems still use sessions, but REST encourages you to minimize server side state.

3. Cacheable

REST encourages you to use caching to improve performance.

Typical examples:

Examples of HTTP headers that affect caching:

http 
Cache-Control: max-age=60, public
ETag: "abc123"
Last-Modified: Tue, 27 Aug 2024 10:00:00 GMT

If you follow REST and use proper HTTP caching headers, you get better performance with less server load.

4. Uniform Interface

The uniform interface is the core idea of REST. It means:

This has several sub-ideas.

Resource based

In REST you think in terms of resources, not actions.

A resource is anything that can be identified and manipulated. Examples:

Each resource has a URI:

You focus on nouns, not verbs in the URL.

Not RESTful style:

More RESTful style:

Manipulation of resources through representations

Clients do not work with the resource directly. They work with a representation of the resource, usually JSON.

For example, the resource might be "user 123 in the database," but the representation you send in the HTTP response is JSON:

json 
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

The client sends representations in requests to create or update resources.

Example:

http 
PUT /users/123
Content-Type: application/json
{
  "name": "Alice Johnson",
  "email": "alice@example.com"
}

The server updates the underlying resource using this representation.

Self descriptive messages

Each HTTP request and response should be self descriptive. That means you can understand it without extra hidden context.

Example response:

http 
HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/123
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com"
}

From this message, you can see:

HATEOAS (Hypermedia as the Engine of Application State)

This is the strictest part of REST and many practical APIs do not fully implement it.

HATEOAS means the API provides links inside responses to show what you can do next.

Example:

json 
{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" },
    "update": { "href": "/users/123", "method": "PATCH" }
  }
}

The idea:

In real life, many APIs are called "RESTful" but ignore HATEOAS. That is common, and usually acceptable, but keep in mind that strict REST includes this concept.

5. Layered System

A REST API can use layers between the client and the actual server, such as:

Clients do not need to know if they talk to the real server or an intermediary.

This is important for:

Example:

Client → API Gateway → Backend Services → Database

From the client's point of view, it still calls https://api.example.com/users, and does not care how many layers exist behind that URL.

6. Code on Demand (Optional)

REST allows, but does not require, the server to send executable code to the client.

Example:

In modern web APIs, this is usually not relevant, especially for mobile or backend to backend APIs. You can safely ignore this constraint for most backend REST API work.

REST vs "RESTful" APIs

Many APIs call themselves REST APIs or RESTful APIs even if they only follow some of the REST ideas.

Typical properties of an API that people call "RESTful":

Many of these APIs:

You do not need to be a "REST police officer." Your goal as a backend developer is:

Examples of RESTful Interactions

To make the ideas concrete, here are some common API interactions and how they look in a RESTful style.

Example: Users Resource

Assume we have a User resource.

ActionHTTP MethodURLRequest BodyResponse Status
List usersGET/usersNone200 OK
Create a new userPOST/usersJSON with user data201 Created
Get one userGET/users/123None200 OK or 404
Replace a userPUT/users/123Full JSON representation200 OK or 204
Update part of userPATCH/users/123Partial JSON representation200 OK or 204
Delete a userDELETE/users/123None204 No Content

Example requests and responses:

1. List users

http 
GET /users HTTP/1.1
Host: api.example.com
Accept: application/json
http 
HTTP/1.1 200 OK
Content-Type: application/json
[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob" }
]

2. Create user

http 
POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
  "name": "Charlie"
}
http 
HTTP/1.1 201 Created
Content-Type: application/json
Location: /users/3
{
  "id": 3,
  "name": "Charlie"
}

3. Get user

http 
GET /users/3 HTTP/1.1
Host: api.example.com
Accept: application/json
http 
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": 3,
  "name": "Charlie"
}

4. Delete user

http 
DELETE /users/3 HTTP/1.1
Host: api.example.com
http 
HTTP/1.1 204 No Content

These examples show how REST uses HTTP methods and status codes to express intent and results, without inventing custom actions.

REST Compared to Other Styles

You may hear about other API styles. REST is not the only one.

Some examples:

REST is simple, human readable, and works very well with HTTP. This is why it is the most common style for public web APIs and for many backend systems.

Benefits of REST for Backend Developers

Using REST ideas in your backend gives you:

If you use HTTP, you should usually design your API in a RESTful way to benefit from HTTP's features and conventions.

What You Need to Remember Now

For now, you do not need to memorize every theoretical detail of REST. Instead, remember these practical points:

In the next chapters, you will apply these ideas to design resources, endpoints, and HTTP methods for real REST APIs.

Views: 10

Comments

Please login to add a comment.

Don't have an account? Register now!

© 2025 Kahibaro
Visitors: 3518 / 24h
Impressum / Imprint
Datenschutz / Data Policy