REST API Design

Этот материал содержит определения и объяснение ключевых концепций REST API Design, включая вопросы для проверки знаний, основные компоненты и теги.

В двух словах

REST — это архитектурный стиль для веб-сервисов, использующий ресурсоориентированный дизайн и HTTP-методы для создания масштабируемых интерфейсов.

Определение

REST (Representational State Transfer) основан на шести ограничениях, включая разделение клиента и сервера и отсутствие состояния. Ресурсы адресуются через URI и передаются в виде представлений (JSON/XML). HTTP-методы (GET, POST, PUT, DELETE) реализуют CRUD-операции. HATEOAS делает API навигируемым. Производительность оптимизируется кешированием и пагинацией.

Ключевые моменты для подготовки

• Richardson Maturity Model для оценки качества API
• Идемпотентность PUT в сравнении с POST
• HATEOAS как принцип гипермедиа
• Безопасность через OAuth 2.0 и HTTPS
• Версионирование через URI или заголовки

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

1. Ресурсы (дизайн URI)
2. HTTP-методы (GET, POST, PUT, DELETE)
3. Коды статуса (200, 201, 400, 401, 404, 500)
4. Форматы медиа (JSON, XML)
5. Механизмы безопасности (HTTPS, OAuth)

Практический пример (API управления пользователями)

Ресурсы:
/users
/users/{id}

GET /users?page=1
POST /users
PUT /users/{id}
DELETE /users/{id}

Преимущества и недостатки

Преимущества	Недостатки
Простота интеграции	Сложная обработка ошибок
Переиспользуемость	Без документации трудна в применении
Масштабируемость	Overfetching для больших ресурсов

Основные вопросы для проверки (с кратким ответом)

1. Какой HTTP-метод идемпотентен, но не безопасен? PUT.
2. Как избежать overfetching? Через специфичные параметры запроса или альтернативные подходы вроде GraphQL.
3. Три риска безопасности REST API? Broken Authentication, Mass Assignment, Injection.
4. Что такое HATEOAS? Hypermedia As The Engine Of Application State — ссылки управляют навигацией.
5. Как документировать REST API? С помощью OpenAPI (Swagger).

Словарь

Термин	Определение
Идемпотентность	Повторное выполнение имеет тот же эффект, что и одно выполнение
HATEOAS	Навигация между ресурсами на основе гипермедиа
OAuth 2.0	Framework для авторизации с делегированным доступом

Анализ темы

• Технический базис: HTTP-протокол, моделирование ресурсов
• Сложности реализации: согласованный дизайн URI, обработка ошибок
• Вопросы безопасности: аутентификация, шифрование
• Обязательства по документации: спецификация OpenAPI
• Экономическая оценка: переиспользование снижает затраты на разработку

Стратегия обучения

1. Начало: Изучите известный API, например GitHub REST API.
2. Углубление: Напишите простую спецификацию OpenAPI (адресная книга).
3. Подготовка к экзамену: Спроектируйте API продукта за 15 минут.
4. Избежание ошибок: Проверьте безопасность с помощью OWASP ZAP.

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

1. https://swagger.io/specification/
2. https://owasp.org/www-project-api-security/
3. https://docs.github.com/rest
4. https://www.postman.com/api-examples/

Дополнительные статьи про REST API

REST API — это основа современных веб-приложений. Следующие материалы помогут вам освоить все аспекты дизайна и разработки REST API.

Основы и концепции

• REST API Основы: HTTP-методы, коды статуса - Полное введение в принципы REST
• REST API Разработка: основы и лучшие практики - Практическое руководство по разработке API
• REST API Основы: Richardson Maturity Model - Продвинутые концепции и уровни зрелости