REST API

Representational State Transfer

[ postman ]

A server resting on a beach and holding a JSON file

Общение между клиентом и сервером, подчиняется правилам, описанным в спецификации API.

REST придумали для стандартизации этих правил.

REST — это стиль общения между клиентом и сервером.

Отличительные черты REST

Клиент-серверная архитектура

Клиент отправляет запросы к серверу, который занимается обработкой и хранением данных.

Разделение обязанностей позволяет дорабатывать и масштабировать клиент и сервер независимо друг от друга.

Отсутствие состояния

Каждый запрос содержит всю необходимую информацию для его обработки сервером, например, JWT токен авторизации с информацией о клиенте.

Противоположность — хранение клиентских сессий на сервере.

Кэширование

Клиент кэширует ответы сервера, чтобы не запрашивать их повторно, если данные не изменились.

Временное хранение данных на клиенте снижает нагрузку на сервер и ускоряет работу.

Унифицированный интерфейс

Ресурсы представлены по единообразным URL-адресам.

URL-адрес содержит название ресурса, действие над которым определяется HTTP методом.

Например, GET /cookies/1

Унифицированный интерфейс

Эндпоинт называется по имени ресурса, над которым производится операция, во множественном числе:

/cookies — ресурс печеньки

HTTP-метод соответствует выполняемой над ресурсом операции:

Метод	Пример	Описание
GET	`GET /cookies/1`	Получить печеньку
POST	`POST /cookies`	Создать печеньку
PUT	`PUT /cookies/1`	Заменить печеньку
PATCH	`PATCH /cookies/1`	Обновить печеньку
DELETE	`DELETE /cookies/1`	Удалить печеньку

HTTP код ответа соответствует результату выполнения запроса:

Код	Значение
`200 OK`	Успешный запрос
`201 Created`	Ресурс создан
`204 No Content`	Успешно, ответ без тела
`400 Bad Request`	Некорректный запрос
`401 Unauthorized`	Аутентификация не пройдена
`403 Forbidden`	Доступ к ресурсу запрещён
`404 Not Found`	Ресурс не найден
`500 Internal Server Error`	Ошибка на сервере

Идемпотентность — повторное выполнение одной и той же операции даёт одинаковый результат.

Идемпотентные HTTP-методы:

GET запрос никогда не должен изменять состояние сервера.
PUT и DELETE запросы не должны изменять состояние сервера при повторном запросе.

Пример требований к REST API

Управление хранилищем печенек

Сервис позволяет получать, добавлять и обновлять печеньки.

Получить все печеньки.

GET /cookies

Пример ответа

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!"
  }
]

Получить печеньку по идентификатору.

GET /cookies/{id}
Пример ответа
```
200 OK

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

Добавить печеньку.

POST /cookies

Запрос в формате json:

Поле	Тип	Обязательность	Ограничения
flavor	строка	+	chocolate, vanilla, cinnamon
size	строка	+	small, medium, large
wish	строка	+	от 1 до 255 символов

Пример ответа

201 Created

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

Если хранилище заполнено — 507 Insufficient Storage с сообщением «Склад заполнен».

Обновить печеньку.

PUT /cookies/{id}

Запрос в формате json:

Поле	Тип	Обязательность	Ограничения
flavor	строка	+	chocolate, vanilla, cinnamon
size	строка	+	small, medium, large

Пример ответа

200 OK

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

Частично обновить печеньку.

PATCH /cookies/{id}

Запрос в формате json:

Поле	Тип	Обязательность	Ограничения
flavor	строка	-	chocolate, vanilla, cinnamon
size	строка	-	small, medium, large

Пример ответа

204 No Content

Формат передачи данных: application/json

Все запросы к API должны выполняться с JWT токеном в заголовке Authorization.

Задача