Чему вы научитесь в этой лекции
- Поймёте, как устроены RESTful API и почему этот стиль так популярен
- Освоите основные принципы REST: Stateless, ресурсы, методы HTTP, представления, HATEOAS, версионирование, обработка ошибок, кэширование
- Получите практические рекомендации по проектированию REST API
- Научитесь отличать удачные и неудачные решения при проектировании интерфейсов
Положение лекции в курсе:
Это вторая лекция второго раздела курса по основам API. В предыдущем материале («Методы проектирования API») мы рассмотрели базовые подходы к созданию удобных и поддерживаемых интерфейсов обмена данными. Следующий шаг — познакомиться с RESTful API, самым популярным сегодня стилем проектирования веб-интерфейсов.
Краткое напоминание: что такое REST?
REST (Representational State Transfer) — архитектурный стиль для взаимодействия между компонентами распределённых систем (чаще всего между клиентом и сервером) через стандартные веб-протоколы, прежде всего HTTP. Главная идея — делать API максимально простым, понятным и совместимым с web-стандартами.
Основные методы проектирования RESTful API
Statelessness (Без сохранения состояния)
Определение:
Каждый запрос клиента содержит всю необходимую информацию для его выполнения. Сервер не хранит сессии или состояние между запросами.
Аналогия:
Представьте почтовое отделение: каждое письмо — отдельное сообщение, которое несёт всю нужную информацию (адрес, отправитель, содержимое). Почтальону не нужно помнить предыдущие письма.
Пример:
При получении корзины покупателя сервер каждый раз получает идентификатор пользователя и список товаров в запросе — а не вспоминает о предыдущем состоянии.
Быстрый итог:
REST API не зависят от предыдущих запросов — каждый запрос самодостаточен.
Ресурсно-ориентированная архитектура
Определение:
Всё представляется в виде ресурсов, у каждого из которых есть уникальный URL (например, /books, /users/123).
Аналогия:
Как полки в библиотеке: каждая книга — отдельный объект с собственным местоположением.
Примеры URL для книжного магазина:
- GET /books — получить все книги
- POST /books — добавить новую книгу
- GET /books/10 — получить информацию о книге с ID 10
Быстрый итог:
В REST API всё — ресурсы с адресами.
Использование стандартных HTTP-методов
Определение:
Операции над ресурсами соответствуют методам HTTP:
- GET — получение информации
- POST — создание нового ресурса
- PUT — обновление существующего
- DELETE — удаление ресурса
Пример:
GET /users/123 // Получить пользователя 123
POST /users // Создать пользователя
PUT /users/123 // Изменить пользователя 123
DELETE /users/123 // Удалить пользователя 123
Быстрый итог:
Методы должны соответствовать своим функциям.
Представления ресурсов
Определение:
Ресурсы передаются в виде стандартных форматов (JSON, XML и др.). На практике чаще всего используется JSON.
Пример ответа:
{
"id": 123,
"name": "Иван Иванов",
"email": "ivan@example.com"
}
Быстрый итог:
Обмен данными идёт через универсальные форматы.
HATEOAS (Гипермедиа как движок состояния приложения)
Определение:
API предоставляет ссылки на связанные действия прямо в ответе. Это помогает клиенту «путешествовать» по API без жёсткой привязки к структуре.
Пример ответа:
{
"id": 456,
"title": "Изучаем API",
"_links": {
"self": { "href": "/books/456" },
"author": { "href": "/authors/789" },
"reviews": { "href": "/books/456/reviews" }
}
}
Аналогия:
Как навигация на сайте: вы всегда видите, куда можно перейти дальше.
Быстрый итог:
API подсказывает клиенту дальнейшие шаги через ссылки.
Версионирование
Определение:
Позволяет менять API без риска сломать работу старых клиентов. Чаще всего версия указывается в URL (/v1/users) или в заголовках (Accept-Version).
Пример:
- GET /v1/books
- GET /v2/books
Быстрый итог:
Версия API помогает управлять изменениями.
Обработка ошибок
Определение:
Сервер возвращает информативные сообщения об ошибках и стандартные коды HTTP (например, 404 — не найдено, 400 — неверный запрос).
Пример сообщения об ошибке:
{
"error": {
"code": 404,
"message": "Книга не найдена"
}
}
Быстрый итог:
Ошибки должны быть понятны разработчику клиента.
Кэширование
Определение:
Механизмы кэширования позволяют уменьшить нагрузку на сервер и ускорить отдачу данных. Для этого используются специальные HTTP-заголовки (Cache-Control, ETag и др.).
Аналогия:
Как закладки в книге: если вы часто обращаетесь к одной странице, удобнее держать её под рукой.
Быстрый итог:
Грамотное кэширование делает API быстрее и дешевле в обслуживании.
Лучшие практики проектирования RESTful API
- Используйте существительные во множественном числе для имён ресурсов: /products, /orders.
- Не усложняйте структуру URL: избегайте глубокой вложенности.
- Соблюдайте единообразие в именовании и структуре.
- Не добавляйте действия (глаголы) в адреса, всё действие определяется методом HTTP.
- Учитывайте безопасность: валидируйте входные данные, используйте HTTPS.
- Документируйте каждый эндпоинт (см. следующий раздел курса).
Практические задания
- Базовый уровень:
Опишите адреса и методы для управления пользователями (users) и заказами (orders) интернет-магазина по REST принципам. - Средний уровень:
Предложите структуру ответа для ресурса orders, учитывая HATEOAS. - Продвинутый уровень:
Придумайте схему версионирования для API, который будет поддерживать несколько типов клиентов (веб, мобильное приложение).
Вопросы для самопроверки
- Почему REST API должны быть stateless?
- Что такое ресурс в терминологии REST?
- Чем отличается GET-запрос от POST-запроса?
- Что даёт использование HATEOAS?
- Какой формат данных предпочтителен для обмена через REST API?
Дополнительные ресурсы для углублённого изучения
- Книга Мартина Фаулера «Patterns of Enterprise Application Architecture» (рекомендуемая к прочтению)
- Документация по HTTP MDN Web Docs
Коротко о главном
RESTful API проектируются так, чтобы быть простыми для понимания и использования всеми разработчиками, знакомыми с web-технологиями. Принципы ресурсо-ориентированности, безсостояния, стандартизации методов и форматов позволяют создавать масштабируемые и надёжные решения. Следуя этим подходам, вы облегчаете себе поддержку и развитие вашего продукта.
В следующей лекции мы подробно рассмотрим особенности проектирования GraphQL API — альтернативного подхода к обмену данными между клиентом и сервером. Обязательно ознакомьтесь с предыдущими материалами курса для лучшего понимания контекста!
Понравился материал? Есть вопросы или опыт работы с REST API? Поделитесь мнением в комментариях — редакция «ОК» всегда отвечает на интересные вопросы и разбирает присланные кейсы!