Принципы проектирования RESTful API
Этот материал — справочник по принципам проектирования RESTful API, с контрольными вопросами, ключевыми моментами и тегами.
Короче говоря
REST (Representational State Transfer) — это архитектурный подход для создания HTTP API: четкие методы, URI ресурсов, коды состояния и отсутствие состояния на сервере.
Основное описание
REST использует HTTP-методы для операций CRUD:
- GET: чтение
- POST: создание
- PUT: полная замена
- PATCH: частичное изменение
- DELETE: удаление
REST следует принципу отсутствия состояния (Statelessness): каждый запрос содержит всю необходимую информацию, сервер не хранит состояние сеанса.
Идемпотентность критична для повторных попыток:
- идемпотентные: GET, PUT, DELETE
- не обязательно идемпотентные: POST, PATCH
Результаты передаются через коды состояния (например, 200, 201, 404, 500). Обычные форматы данных — JSON/XML.
Ключевые точки для проверки знаний
- HTTP-методы для CRUD
- REST не сохраняет состояние
- Идемпотентность: повторения не должны дублировать побочные эффекты
- URI ресурсов, например
/api/users/123 - Коды состояния (200, 201, 404, 500) (важно на экзаменах)
- PATCH изменяет только отдельные поля
- Безопасность: HTTPS, Token-Auth, CORS
- Документация: OpenAPI/Swagger (обязательна)
Основные компоненты
- HTTP-методы
- Соглашения для URI ресурсов
- Коды состояния (2xx/4xx/5xx)
- Соответствие REST (Richardson)
- Правила идемпотентности
- Отсутствие состояния
- Content Negotiation (Accept/Content-Type)
- JSON/XML
- Аутентификация (Bearer/API-Key)
- OpenAPI/Swagger
Практический пример (API пользователей)
GET /users
POST /users
GET /users/1
PUT /users/1
PATCH /users/1
DELETE /users/1
Плюсы и минусы
Плюсы
- Просто, понятно
- Стандартный протокол (HTTP)
- Независим от платформы и языка
- Хорошо масштабируется
Минусы
- Нет встроенного управления сеансами
- Может требовать много запросов (chatty)
- Для сложных операций нужна чистая архитектура
Типичные экзаменационные вопросы (с кратким ответом)
- Что означает stateless? Сервер не хранит состояние сеанса; запрос должен быть полным.
- Какие методы идемпотентны? GET, PUT, DELETE.
- PUT против PATCH? PUT заменяет полностью, PATCH только отдельные поля.
- Что означает 201? Ресурс был создан.
Развернутый ответ
REST — основа современных веб-API. На экзаменах и в проектах нужно четко документировать эндпоинты, правильно выбирать методы и корректно использовать коды состояния.
Стратегия обучения
- Тестируй API с помощью Postman/curl.
- Напиши небольшой API с CRUD-маршрутами.
- Выучи наизусть методы, коды состояния, идемпотентность.
- Используй PUT/DELETE только как идемпотентные операции.
Анализ темы
- Ядро: HTTP, дизайн URI, JSON
- Сложности: версионирование, обработка ошибок, аутентификация
- Безопасность: контроль доступа, шифрование, CORS
- Документация: OpenAPI, примеры, каталог ошибок
- Экономичность: стандартизация экономит время