REST API
Способ, которым программы обмениваются данными по HTTP: каждый объект доступен по своему адресу, а действия задаются методами GET, POST, PUT, DELETE.
API (Application Programming Interface) — договор о том, как одна программа обращается к другой. REST API — самый распространенный стиль таких договоров в вебе. Данные представлены как ресурсы со своими адресами — заказы, клиенты, платежи, — а действия с ними выполняются стандартными методами протокола HTTP. Мобильное приложение банка, личный кабинет на сайте и интеграция двух учетных систем чаще всего общаются именно так.
Принципы REST сформулировал Рой Филдинг в своей диссертации в 2000 году.
Ресурсы и методы
| Запрос | Что делает |
|---|---|
GET /orders |
Получить список заказов |
GET /orders/42 |
Получить заказ № 42 |
POST /orders |
Создать новый заказ |
PUT /orders/42 |
Заменить заказ № 42 целиком |
PATCH /orders/42 |
Изменить отдельные поля заказа |
DELETE /orders/42 |
Удалить заказ |
Как выглядит обмен
curl -H "Authorization: Bearer <token>" https://api.example.ru/orders/42Ответ приходит обычно в формате JSON вместе с кодом состояния: 200 — успешно, 201 — создано, 400 — ошибка в запросе, 401 — нужна авторизация, 404 — не найдено, 500 — ошибка на сервере.
{ "id": 42, "status": "paid", "amount": 15000 }Принципы REST
- Без состояния (stateless). Каждый запрос содержит все нужное для его обработки, сервер не помнит предыдущие. Поэтому серверы легко масштабировать за балансировщиком нагрузки.
- Единообразие. Одни и те же методы и коды ответов для всех ресурсов.
- Кэширование. Ответы на GET-запросы можно сохранять и переиспользовать.
- Идемпотентность. Повтор GET, PUT или DELETE дает тот же результат, поэтому их безопасно повторять при сбое сети. POST — нет: повтор может создать второй заказ, и от этого защищаются ключами идемпотентности.
Безопасность
Доступ к API выдают по токенам — часто это JWT, полученные по протоколу OAuth 2.0. Запросы между системами дополнительно подписывают с помощью HMAC, а весь обмен идет по защищенному каналу TLS.
Документация и версии
Хороший API описан в спецификации OpenAPI (Swagger): по ней генерируют документацию и клиентский код. Изменения, ломающие совместимость, выпускают в новой версии (/v2/orders), чтобы старые клиенты продолжали работать. Проектирование и поддержка API — основа интеграций в разработке информационных систем. Альтернатива для сложных интерфейсов — GraphQL, где клиент сам выбирает нужные поля.