Общение между клиентом и сервером, подчиняется правилам, описанным в спецификации API.
REST придумали для стандартизации этих правил.
REST — это стиль общения между клиентом и сервером.
REST API
Representational State Transfer
Отличительные черты 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.
Задача
Уровень повышен!
