REST API

Representational State Transfer

[ postman ]

A server resting on a beach and holding a JSON file

Communication between client and server follows the rules defined in the API specification.

REST was invented to standardize these rules.

REST is a style of communication between client and server.

Key Features of REST

Client-Server Architecture

The client sends requests to the server, which handles processing and data storage.

Separation of concerns allows the client and server to be developed and scaled independently.

Statelessness

Each request contains all the information necessary for the server to process it, such as a JWT authorization token with client information.

The opposite approach is storing client sessions on the server.

Caching

The client caches server responses to avoid making repeated requests when the data hasn't changed.

Temporary data storage on the client reduces server load and improves performance.

Uniform Interface

Resources are represented by consistent URL addresses.

The URL contains the resource name, and the action is determined by the HTTP method.

For example, GET /cookies/1

Uniform Interface

The endpoint is named after the resource being operated on, in plural form:

/cookies — cookie resource

The HTTP method matches the operation performed on the resource:

Method	Example	Description
GET	`GET /cookies/1`	Retrieve a cookie
POST	`POST /cookies`	Create a cookie
PUT	`PUT /cookies/1`	Replace a cookie
PATCH	`PATCH /cookies/1`	Update a cookie
DELETE	`DELETE /cookies/1`	Delete a cookie

The HTTP response code reflects the result of the request:

Code	Meaning
`200 OK`	Successful request
`201 Created`	Resource created
`204 No Content`	Success, no content in response
`400 Bad Request`	Bad request
`401 Unauthorized`	Authentication failed
`403 Forbidden`	Access to resource is forbidden
`404 Not Found`	Resource not found
`500 Internal Server Error`	Server error

Idempotency — repeating the same operation yields the same result.

Idempotent HTTP methods:

GET the request must never change the server state.
PUT and DELETE requests must not change the server state if repeated.

Example of REST API Requirements

Cookie Storage Management

The service allows retrieving, adding, and updating cookies.

Retrieve all cookies.

GET /cookies

Example response

200 OK

[
  {
    "id": 1,
    "flavor": "vanilla",
    "size": "medium",
    "wish": "May your day be sweet!"
  },
  {
    "id": 2,
    "flavor": "chocolate",
    "size": "small",
    "wish": "Success!"
  },
  {
    "id": 3,
    "flavor": "cinnamon",
    "size": "large",
    "wish": "Warmth and comfort!"
  }
]

Retrieve a cookie by identifier.

GET /cookies/{id}

Example response

200 OK

{
    "id": 1,
    "flavor": "vanilla",
    "size": "medium",
    "wish": "May your day be sweet!"
}

Add a cookie.

POST /cookies

Request in JSON format:

Field	Type	Required	Restrictions
flavor	string	+	chocolate, vanilla, cinnamon
size	string	+	small, medium, large
wish	string	+	1 to 255 characters

Example response

201 Created

{
    "id": 1,
    "flavor": "vanilla",
    "size": "medium",
    "wish": "May your day be sweet!"
}

If the storage is full — 507 Insufficient Storage with the message “Storage is full”.

Update a cookie.

PUT /cookies/{id}

Request in JSON format:

Field	Type	Required	Restrictions
flavor	string	+	chocolate, vanilla, cinnamon
size	string	+	small, medium, large

Example response

200 OK

{
    "id": 1,
    "flavor": "vanilla",
    "size": "medium",
    "wish": "May your day be sweet!"
}

Partially update a cookie.

PATCH /cookies/{id}

Request in JSON format:

Field	Type	Required	Restrictions
flavor	string	-	chocolate, vanilla, cinnamon
size	string	-	small, medium, large

Example response

204 No Content

Data format: application/json

All API requests must be sent with a JWT token in the Authorization header.

Task