REST (Representational State Transfer) — это архитектурный стиль программного обеспечения, используемый для проектирования интерфейсов сетевых приложений.
REST API (Application Programming Interface) — это интерфейс веб-службы, построенный на принципах REST, позволяющий различным системам взаимодействовать и обмениваться данными по протоколу HTTP.

Основные особенности REST API включают:
- Отсутствие состояния (Stateless): каждый запрос содержит всю информацию, необходимую для обработки этого запроса
- Ориентированность на ресурсы (Resource-based): все данные рассматриваются как ресурсы, идентифицируемые с помощью URI
- Унифицированный интерфейс: использует стандартные методы HTTP (GET, POST, PUT, DELETE и т. д.)
- Кэшируемость (Cacheable): ответы могут быть явно помечены как кэшируемые или некэшируемые
Основные концепции REST API
1. Ресурс
В REST ресурс — это любая информация, которая может быть поименована, например пользователь, товар, заказ и т. д. Каждый ресурс имеет уникальный идентификатор (URI).
2. Методы HTTP
REST API используют стандартные методы HTTP для определения операций над ресурсами:
| HTTP-метод | Описание | Идемпотентность | Безопасность |
|---|---|---|---|
| GET | Получение ресурса | Да | Да |
| POST | Создать новый ресурс | нет | нет |
| PUT | Обновить весь ресурс | Да | нет |
| PATCH | Частично обновить ресурс | нет | нет |
| DELETE | Удаление ресурса | Да | нет |
3. Коды состояния
HTTP-коды состояния указывают результат обработки запроса:
| Код состояния | Категория | Распространённые коды состояния |
|---|---|---|
| 2xx | Успех | 200 OK, 201 Created |
| 3xx | Перенаправление | 301 Перемещено навсегда |
| 4xx | Ошибки клиента | 400 Bad Request, 404 Not Found |
| 5xx | Ошибки сервера | 500 Внутренняя ошибка сервера |
4. Форматы данных
Распространённые форматы обмена данными для REST API:
- JSON(JavaScript Object Notation)
- XML(eXtensible Markup Language)
- Иногда также используются такие форматы, как YAML, CSV и т. д.
Лучшие практики проектирования REST API
1. Принципы проектирования URI
- Используйте существительные вместо глаголов для представления ресурсов
- Хорошо:
/users - Плохо:
/getUsers
- Хорошо:
- Используйте строчные буквы и дефисы (-)
- Избегайте расширений файлов
- Используйте формы множественного числа для коллекций
- Представляйте отношения иерархически:
/users/{id}/orders
2. Версионирование
Рекомендуется включать информацию о версии API в URI или заголовки запроса:
- Путь URI:
/v1/users - Заголовок запроса:
Accept: application/vnd.myapi.v1+json
3. Фильтрация, сортировка и пагинация
Для коллекционных ресурсов предусмотрите параметры запроса:
- Фильтрация:
/users?role=admin - Сортировка:
/users?sort=-created_at - Пагинация:
/users?page=2&limit=10
4. Безопасность
- Используйте HTTPS
- Реализуйте аутентификацию (OAuth2, JWT)
- Ограничьте частоту запросов
- Проверяйте входные данные
Пример REST API
Пример API управления пользователями
Пример
GET /api/v1/users
Accept: application/json
# Создать нового пользователя
POST /api/v1/users
Content-Type: application/json
{
"name": "Чжан Сань",
"email": "zhangsan@example.com"
}
# Получить конкретного пользователя
GET /api/v1/users/123
Accept: application/json
# Обновить информацию о пользователе
PUT /api/v1/users/123
Content-Type: application/json
{
"name": "Zhang San (Обновлено)",
"email": "new-email@example.com"
}
# Удалить пользователя
DELETE /api/v1/users/123
Пример ответа
Пример
{
"status": "success",
"data": {
"id": 123,
"name": "Чжан Сань",
"email": "zhangsan@example.com",
"created_at": "2023-01-01T00:00:00Z"
}
}
// Ответ с ошибкой
{
"status": "error",
"message": "Пользователь не найден",
"code": 404
}
Инструменты для тестирования REST API
- Postman: мощный инструмент для тестирования API
- cURL: инструмент командной строки
- Insomnia: лёгкий клиент для тестирования API
- Swagger/OpenAPI: инструмент документирования и тестирования API
Пример cURL
Пример
curl -X GET https://api.example.com/users/123 \
-H "Accept: application/json"
# POST-запрос
curl -X POST https://api.example.com/users \
-H "Content-Type: application/json" \
-d '{"name":"Li Si","email":"lisi@example.com"}'
Фреймворки для разработки REST API
В зависимости от языка программирования для разработки REST API доступны различные фреймворки:
| Язык | Популярные фреймворки |
|---|---|
| JavaScript | Express.js, NestJS |
| Python | Django REST Framework, Flask |
| Java | Spring Boot |
| PHP | Laravel, Symfony |
| Ruby | Ruby on Rails |
| Go | Gin, Echo |
I. Основные принципы проектирования
1. Применяйте четкие соглашения об именовании
Основные принципы:
- Используйте существительные (а не глаголы) для представления ресурсов
- Используйте формы множественного числа для коллекций
- Поддерживайте согласованность и интуитивность именования
Примеры:
✅ Хороший дизайн: /users, /products, /orders
-
❌ Плохой дизайн: /getUsers, /addProduct, /all-orders
Дополнительные рекомендации:
- Используйте иерархическое именование ресурсов, чтобы отражать связи между ресурсами:
/companies/{companyId}/departments/{departmentId}/employees - Чтобы улучшить читаемость, используйте дефисы (kebab-case) в именах ресурсов, состоящих из нескольких слов:
/shipping-addressesвместо/shippingaddresses - Поддерживайте согласованность именования при итерациях версий API и избегайте ненужных изменений, которые вызывают путаницу у клиентов.
2. Правильно используйте методы HTTP
Базовое использование:
- GET: Чтение ресурса (идемпотентно)
- POST: Создание нового ресурса
- PUT: Обновление всего ресурса (идемпотентно)
- PATCH: Частичное обновление ресурса
- DELETE: удаление ресурса (идемпотентно)
Примеры:
GET /users # 获取用户列表 GET /users/123 # 获取特定用户 POST /users # 创建新用户 PUT /users/123 # 完全更新用户 PATCH /users/123 # 部分更新用户 DELETE /users/123 # 删除用户
Дополнительные рекомендации:
- Поймите важность идемпотентности: GET, PUT и DELETE — идемпотентные операции; многократные вызовы дают одинаковый результат.
- Для пакетных операций рассмотрите использование POST вместо PUT, потому что PUT обычно предполагает, что клиент явно указывает идентификатор ресурса.
- При проектировании операций PATCH рассмотрите использование стандартных форматов, таких как JSON Patch (RFC 6902) или JSON Merge Patch (RFC 7386).
- Для сложных операций можно использовать расширения ресурсов:
POST /users/123/activateСравнениеPOST /activateUser/123Больше соответствует принципам REST
3. Используйте подходящие коды состояния HTTP
Распространённые коды состояния:
- 200 OK: Запрос успешно выполнен
- 201 Created: Ресурс успешно создан
- 204 No Content: Успех, но содержимое не возвращается (например, операция DELETE)
- 400 Bad Request: Ошибка клиента
- 401 Unauthorized: Не аутентифицирован
- 403 Forbidden: нет разрешения
- 404 Not Found: ресурс не существует
- 409 Conflict: конфликт ресурса
- 500 Internal Server Error: ошибка сервера
Рекомендации по расширениям:
- Используйте более детализированные коды состояния для повышения выразительности API:
- 429 Too Many Requests: превышена частота запросов
- 405 Method Not Allowed: неподдерживаемый метод HTTP
- 415 Unsupported Media Type: неподдерживаемый тип содержимого
- 422 Unprocessable Entity: семантическая ошибка
- Чтобы упростить обработку на клиенте, придерживайтесь единообразия в основных категориях ошибок: ошибки клиента (4xx) и ошибки сервера (5xx)
- Всегда предоставляйте содержательные сообщения об ошибках и коды ошибок вместе с кодами состояния
II. Дизайн запросов и фильтрации
4. Реализуйте эффективную пагинацию
Базовая реализация:
- Используйте
limitиoffsetилиpageиsizeparameters - Включайте метаданные пагинации в ответ
Пример:
GET /products?limit=20&offset=40 GET /products?page=3&size=20
Пример ответа:
{
"data": [...],
"pagination": {
"total": 523,
"pages": 27,
"current_page": 3,
"per_page": 20,
"next": "/products?page=4&size=20",
"prev": "/products?page=2&size=20"
}
}
Рекомендации по расширениям:
- Рассмотрите пагинацию на основе курсора, особенно при работе с большими наборами данных или часто обновляемыми данными
- Установите разумные значения пагинации по умолчанию и максимальные ограничения, чтобы чрезмерно большие запросы не влияли на производительность
- Предоставляйте ссылки HATEOAS в ответах пагинации для навигации клиента (например, ссылки next/prev в примере выше)
- Для данных временных рядов можно использовать пагинацию по времени:
GET /events?since=2023-01-01T00:00:00Z&until=2023-01-31T23:59:59Z
5. Обеспечьте гибкую фильтрацию, сортировку, поиск
Базовая реализация:
- Используйте параметры запроса для фильтрации:
?status=active - Используйте
sortпараметр для сортировки:?sort=created_at - Поддерживайте сортировку по нескольким полям и порядок по возрастанию/убыванию:
?sort=price:asc,rating:desc
Пример:
GET /products?category=electronics&price_min=100&price_max=500&sort=price:asc GET /users?role=admin&search=john
Рекомендации по расширениям:
- Предоставьте синтаксис выражений для сложных запросов:
?price=gt:100,lt:500 - Реализуйте частичное сопоставление и опции нечёткого поиска:
?name=like:john - Поддержите выбор полей, позволяя клиентам указывать нужные им поля:
?fields=id,name,email - Рассмотрите возможность реализации GraphQL-эндпоинтов как дополнения для особо сложных запросов
- Предоставьте предопределённые фильтры для распространённых комбинаций фильтров:
?filter=recentМожет быть эквивалентно?created_after=30days&sort=created_at:desc
6. Реализуйте эффективное версионирование API
Основные методы:
- Версия в URL-пути:
/api/v1/users - Версия в параметре запроса:
/api/users?version=1 - Версия в заголовке запроса:
Accept: application/vnd.company.v1+json
Рекомендации по расширениям:
- Версионирование в URL-пути наиболее интуитивно понятно, но приводит к нестабильным URI
- Версионирование через заголовок запроса сохраняет URI стабильными, но менее интуитивно для клиентов
- Следуйте принципам семантического версионирования при итерации версий:
- Обратно совместимые изменения используют минорные номера версий (v1.1)
- Несовместимые изменения используют мажорные номера версий (v2)
- Обеспечьте период миграции между старой и новой версиями, чтобы клиенты могли плавно перейти
- Четко указывайте статус жизненного цикла каждой версии API в документации: в разработке, стабильная, устаревшая, выведена из эксплуатации
III. Проектирование ответов
7. Разработайте согласованную структуру ответов
Базовая структура:
- Используйте объекты-конверты, чтобы отличать данные от метаданных
- Поддерживайте единообразный формат ответов об ошибках
Пример успешного ответа:
{
"status": "success",
"data": {
"id": 123,
"name": "Example Product",
"price": 99.99
},
"meta": {
"timestamp": "2023-06-15T08:30:00Z"
}
}
Пример ответа об ошибке:
{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": [
{"field": "email", "message": "Must be a valid email address"}
]
},
"meta": {
"timestamp": "2023-06-15T08:30:00Z",
"request_id": "req-123456"
}
}
Рекомендации по расширениям:
- Включайте уникальные коды ошибок в ответы об ошибках для диагностики и обращения к документации
- Для сложных ошибок предоставляйте структурированные сведения об ошибках, особенно для ошибок валидации форм
- Включайте идентификатор запроса (request_id) для отслеживания в логах и поддержки клиентов
- Рассмотрите поддержку интернационализации, предоставляя многоязычные версии сообщений об ошибках или сопоставления кодов ошибок
- Избегайте утечки конфиденциальной информации или деталей реализации в сообщениях об ошибках
8. Реализуйте принципы HATEOAS
Основная концепция:
- HATEOAS(Hypermedia as the Engine of Application State)
- Включайте ссылки на связанные ресурсы в ответы, чтобы сделать API самоописываемым
Пример:
{
"data": {
"id": 123,
"name": "John Doe"
},
"links": {
"self": "/users/123",
"orders": "/users/123/orders",
"update": {"href": "/users/123", "method": "PUT"},
"delete": {"href": "/users/123", "method": "DELETE"}
}
}
Рекомендации по расширениям:
- Используйте стандартизированные имена отношений ссылок (как определено в спецификациях HAL или JSON:API)
- Включайте контекстную информацию для ссылок, такую как HTTP-метод и требуемый тип медиа
- Динамически генерируйте ссылки на основе разрешений пользователя, показывая только действия, доступные текущему пользователю
- Рассмотрите использование JSON Schema для предоставления самоописания форматов входных данных
9. Выберите подходящие форматы сериализации
Распространённые форматы:
- JSON: наиболее часто используемый, лёгкий и простой в разборе
- XML: более строгий, но более многословный
- MessagePack: бинарный формат, подходит для сценариев, критичных к производительности
Рекомендации по расширениям:
- Используйте согласование содержимого для поддержки нескольких форматов: клиент использует
Acceptзаголовок для указания желаемого формата - Для JSON придерживайтесь единого соглашения об именовании (camelCase или snake_case)
- Учитывайте требования особых сценариев:
- Формат CSV подходит для экспорта больших объёмов данных
- Protocol Buffers или gRPC подходят для высокопроизводительного взаимодействия микросервисов
- JSON-LD подходит для сценариев, требующих семантических данных
- Обеспечьте согласованные модели данных и имена полей в различных форматах
IV. Безопасность и производительность
10. Реализуйте эффективную аутентификацию и авторизацию
Часто используемые методы:
- API-ключи: подходят для взаимодействия между сервисами
- OAuth 2.0: подходит для авторизации третьих сторон
- JWT (JSON Web Tokens): подходит для аутентификации без сохранения состояния
Рекомендации по расширениям:
- Выбирайте подходящие потоки авторизации для разных сценариев использования API:
- Пользователь — сервер: поток кода авторизации
- Сервер — сервер: поток учетных данных клиента
- Реализуйте детализированное управление разрешениями, следуя принципу наименьших привилегий
- Реализуйте механизмы ротации и отзыва API-ключей
- Используйте стандартные области действия OAuth 2.0 для определения разрешений
- Рассмотрите внедрение управления доступом на основе атрибутов (ABAC) для сложных сценариев авторизации
11. Реализуйте ограничение скорости и троттлинг
Базовая реализация:
- Используйте ограничение частоты запросов для защиты API
- Предоставляйте информацию о лимитах в заголовках ответа
Пример заголовка ответа:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1623760800
Рекомендации по расширениям:
- Реализуйте многоуровневые лимиты:
- Ограничивайте по IP-адресу (предотвращайте анонимные злоупотребления)
- Ограничивайте по пользователю/API-ключу (справедливое использование)
- Ограничивайте по ресурсу/эндпоинту (защищайте чувствительные операции)
- Предлагайте премиум-тарифы или опции масштабирования по требованию
- Используйте алгоритмы token bucket или leaky bucket для обработки пикового трафика
- Реализуйте адаптивный троттлинг для динамической корректировки лимитов в зависимости от нагрузки на систему
- Обеспечьте приоритетные каналы или зарезервированную пропускную способность для критически важных клиентов
12. Используйте кэширование надлежащим образом
Базовая реализация:
- Используйте заголовки ETags и If-None-Match
- Устанавливайте подходящие директивы Cache-Control
Пример:
Cache-Control: max-age=3600, must-revalidate ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Рекомендации по расширениям:
- Задавайте разные стратегии кэширования в зависимости от типа ресурса:
- Статическое содержимое: больший max-age
- Персональные данные: меньший max-age или директива private
- Часто изменяющиеся данные: используйте ETag вместо max-age
- Реализуйте условные запросы (If-Modified-Since, If-None-Match) для сокращения использования пропускной способности
- Рассмотрите реализацию кэширования на уровне API-шлюза или CDN
- Предусмотрите механизмы инвалидации кэша, особенно для ресурсов, которые должны обновляться внезапно
- Используйте теги кэша для детализированного управления кэшем
13. Поддержка сжатия содержимого
Базовая реализация:
- Поддержка сжатия gzip и Brotli
- Используйте заголовки Accept-Encoding и Content-Encoding
Рекомендации по расширениям:
- Автоматически применяйте сжатие к большим ответам, но избегайте сжатия небольших ответов (<1KB)
- Оптимизируйте уровни сжатия для разных типов содержимого
- В чувствительных к производительности сценариях рассмотрите предварительное сжатие распространенных ответов
- Отслеживайте коэффициент сжатия и использование CPU, чтобы найти оптимальный баланс
- Рассмотрите обработку сжатия на уровне прокси/шлюза, чтобы снизить нагрузку на серверы приложений
V. Документация и удобство сопровождения
14. Предоставьте исчерпывающую документацию API
Базовая реализация:
- Используйте спецификацию OpenAPI/Swagger
- Включайте примеры запросов и ответов
Дополнительные рекомендации:
- Примените подход "docs-as-code", версионируя спецификацию API вместе с кодом
- Предоставьте интерактивный браузер API, позволяющий разработчикам тестировать API напрямую
- Включите руководства для типовых сценариев использования и интеграции
- Предоставьте примеры фрагментов кода для каждой конечной точки (на нескольких языках программирования)
- Внедрите журнал изменений API, в котором четко отмечаются устаревшие и новые функции
- Рассмотрите создание сообщества разработчиков или форума для обмена знаниями
15. Мониторинг и логирование
Базовая реализация:
- Записывайте время запросов/ответов
- Отслеживайте частоту ошибок и шаблоны использования
Дополнительные рекомендации:
- Внедрите распределенную трассировку с использованием W3C Trace Context или аналогичных стандартов
- Настройте многомерные метрики мониторинга:
- Производительность эндпоинтов (задержка P95/P99)
- Частота ошибок и распределение по типам
- Паттерны использования клиентами
- Потребление ресурсов (CPU, память, пропускная способность)
- Внедрите интеллектуальные оповещения, которые обнаруживают аномальные паттерны, а не простые пороговые значения
- Предоставьте консоль разработчика, позволяющую потребителям API просматривать свою статистику использования
- Используйте структурированные форматы логов (например, JSON) для упрощения анализа и поиска по логам
16. Предоставляйте полезную информацию для отладки ошибок
Базовая реализация:
- Предоставляйте понятные сообщения об ошибках
- Включайте уникальные коды ошибок
Дополнительные рекомендации:
- Настраивайте подробность ошибок в зависимости от окружения (избегайте утечки конфиденциальной информации в продакшене)
- Реализуйте центр ошибок, который сопоставляет коды ошибок с подробными руководствами по устранению неполадок
- Предоставляйте контекстно-зависимые ссылки на справку
- Предоставляйте автоматические предложения по исправлению распространённых ошибок
- Предоставляйте более подробные трассировки стека и контекст в средах разработки
- Реализуйте механизмы автоматического отчёта о критических ошибках
VI. Расширенные вопросы проектирования
17. Пакетная обработка и асинхронные операции
Пакетная обработка:
- Поддерживайте пакетные операции создания, обновления и удаления
- Предоставляйте параметры обработки частичного успеха
Примеры пакетных операций:
POST /users/batch
{
"operations": [
{"method": "POST", "path": "/users", "body": {"name": "User 1"}},
{"method": "PUT", "path": "/users/123", "body": {"name": "Updated User"}}
]
}
Асинхронные операции:
- Возвращайте 202 Accepted для длительных задач
- Предоставляйте конечные точки статуса задачи
Примеры асинхронных потоков:
POST /reports/generate
Response: 202 Accepted
Location: /tasks/abc-123
GET /tasks/abc-123
Response: {"status": "processing", "progress": 45, "eta": "30s"}
GET /tasks/abc-123
Response: {"status": "completed", "result": "/reports/xyz-789"}
Дополнительные рекомендации:
- Реализуйте асинхронные уведомления на основе вебхуков, которые выполняют обратный вызов клиента при завершении задачи
- Предусмотрите варианты атомарности для пакетных операций (все успешно или все неудачно)
- Поддерживайте зависимости в пакетных операциях (одна операция зависит от результата другой)
- Предоставьте механизмы приоритета задач и возможности отмены
- Реализуйте стратегии повторных попыток для задач и механизмы обработки сбоев
18. Учитывайте эволюцию проектирования API
Основные принципы:
- Используйте дополнение, а не изменение
- Избегайте удаления; сначала пометьте устаревшим, затем удалите
- Поддерживайте обратную совместимость
Дополнительные рекомендации:
- Установите четкую политику жизненного цикла API:
- Ожидания стабильности для версий Preview/Alpha/Beta
- Период устаревания (обычно не менее 6-12 месяцев)
- Период сопровождения для версий с долгосрочной поддержкой (LTS)
- Используйте feature flags для постепенного внедрения новых функций
- Внедрите аналитику использования API, чтобы понимать, какие endpoints и функции больше не используются
- Предоставьте инструменты миграции и примеры, чтобы помочь клиентам перейти на новые версии
- Продумайте точки расширения на этапе проектирования, такие как поддержка пользовательских полей или метаданных
VII. Отраслевые оптимизации и новые тенденции
Оптимизация API мобильных приложений
- Реализуйте endpoints GraphQL, чтобы мобильные клиенты могли точно запрашивать нужные им данные
- Поддержка частичных ответов для сокращения использования пропускной способности:
?fields=id,name,thumbnail - Предоставьте API пакетной предзагрузки, чтобы сократить количество сетевых обменов
- Рассмотрите адаптивный дизайн, который регулирует размер ответа в зависимости от возможностей устройства и условий сети
- Реализуйте механизмы инкрементальной синхронизации, которые передают только изменённые данные
Аспекты API для IoT (Интернет вещей)
- Поддерживайте легковесные протоколы (такие как MQTT или CoAP)
- Реализуйте модели состояния устройств и двустороннюю связь
- Оптимизируйте использование пропускной способности с помощью двоичных форматов и сжатия
- Проектируйте стратегии автономной работы и разрешения конфликтов
- Предоставляйте API управления устройствами и обновления прошивки
Подход к разработке API-First
- Примите подход design-first, а не code-first
- Используйте модели API для управления процессом разработки (например, генерацию кода из спецификаций OpenAPI)
- Внедрите процессы проверки дизайна API для обеспечения согласованности и качества
- Создавайте руководства по стилю API и документацию по лучшим практикам
- Используйте контрактное тестирование, чтобы гарантировать соответствие реализаций спецификациям
VIII. Резюме
Хорошо спроектированный REST API требует тщательного балансирования множества факторов, включая удобство использования, производительность, безопасность и сопровождаемость. Следуя этим лучшим практикам, команды разработчиков могут создавать API, которые одновременно соответствуют принципам REST и отвечают потребностям современных приложений. Ключ — поддерживать согласованность, интуитивность и всегда мыслить с точки зрения потребителей API. По мере развития API-экономики качественный дизайн API станет ключевым фактором успеха организации.
IX. Дополнительная литература
- RESTful веб-API (Леонард Ричардсон, Майк Амундсен)
- Паттерны проектирования API (JJ Geewax)
- Проектирование веб-API: лучшие практики создания современных приложений (Арно Лоре)
- Руководство по безопасности REST API (OWASP)
- Модель зрелости Ричардсона: понимание уровней эволюции REST API