Принципы RESTful-дизайна

Этот материал объясняет принципы RESTful-дизайна с проверочными вопросами и ключевыми терминами.

Суть

REST — это архитектурный подход для API на основе HTTP с четко определёнными методами, ресурсами, кодами состояния и отсутствием состояния на сервере.

Техническое определение

REST представляет собой лёгкий протокол на основе HTTP для обмена ресурсами между клиентом и сервером. Он опирается на HTTP-методы: GET (чтение), POST (создание), PUT (полная замена), DELETE (удаление), PATCH (частичное обновление). REST строится на принципе statelessness: каждый запрос должен содержать всю необходимую информацию, а сервер не хранит данные сессии. Идемпотентность играет ключевую роль: GET, PUT и DELETE являются идемпотентными (повторное выполнение имеет тот же эффект), а POST и PATCH нет. REST использует стандартизированные коды состояния (200 OK, 201 Created, 404 Not Found, 500 Server Error) для обозначения результатов операций.

Ключевые элементы для экзамена

• GET, POST, PUT, DELETE, PATCH: HTTP-методы для операций CRUD
• REST не сохраняет состояние, отслеживание сессий отсутствует
• Идемпотентность: повторные запросы действуют только один раз (например, при PUT)
• URI, ориентированные на ресурсы, например /api/users/123
• Использование кодов состояния HTTP (200, 201, 404, 500 и т.д.)
• PATCH обновляет только части объекта
• Аспекты безопасности: аутентификация через токен, HTTPS, CORS
• Документирование интерфейсов с OpenAPI или Swagger

Основные компоненты

1. HTTP-методы (GET, POST, PUT, DELETE, PATCH)
2. Соглашения по URI (на основе ресурсов)
3. Коды состояния (2xx, 4xx, 5xx)
4. Соответствие REST (Richardson Maturity Model)
5. Правила идемпотентности
6. Архитектура без состояния
7. Content Negotiation (заголовки Accept и Content-Type)
8. JSON/XML в качестве форматов данных
9. Аутентификация (Bearer Token, API Keys)
10. Документация OpenAPI/Swagger

Практический пример

// Пример: REST-API для управления пользователями
GET /users → список всех пользователей
POST /users → создать нового пользователя
GET /users/1 → показать пользователя с ID 1
PUT /users/1 → полностью заменить пользователя
PATCH /users/1 → обновить только определённые поля
DELETE /users/1 → удалить пользователя

Пояснение: каждый метод соответствует чётко определённому действию над ресурсом. URI остаётся неизменным, метод определяет семантику операции.

Достоинства и недостатки

Достоинства

• Простота, легко понять
• Использует стандартные протоколы (HTTP)
• Независим от платформы и языка программирования
• Хорошо масштабируется

Недостатки

• Нет встроенного управления сессиями
• Может быть неэффективным при большом количестве вызовов API
• Отсутствует стандартизация для сложных операций

Типичные вопросы на экзамене (с кратким ответом)

1. Что означает “stateless” в REST? Сервер не сохраняет данные сессии, каждый запрос должен быть полным и независимым.
2. Какие HTTP-методы являются идемпотентными? GET, PUT, DELETE.
3. В чём разница между PUT и PATCH? PUT заменяет объект целиком, PATCH изменяет только определённые поля.
4. Что обозначает код 201? Ресурс успешно создан.
5. REST против SOAP? REST легковесен, использует HTTP напрямую, SOAP основан на XML и имеет больший объём.
6. Как адресовать ресурс? Через URI, например /users/123.
7. Какие меры безопасности применять в REST-API? HTTPS, аутентификация по токену, контроль доступа.
8. Почему идемпотентность важна? Повторные попытки при сбое сети не вызывают нежелательных побочных эффектов.

Основные источники

1. https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design
2. https://developer.mozilla.org/de/docs/Web/HTTP/Methods
3. https://restfulapi.net/
4. https://swagger.io/specification/
5. https://www.howtographql.com/basics/1-graphql-vs-rest/