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

  1. Postman: мощный инструмент для тестирования API
  2. cURL: инструмент командной строки
  3. Insomnia: лёгкий клиент для тестирования API
  4. Swagger/OpenAPI: инструмент документирования и тестирования API

Пример cURL

Пример

# GET-запрос
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. Дополнительная литература

  1. RESTful веб-API (Леонард Ричардсон, Майк Амундсен)
  2. Паттерны проектирования API (JJ Geewax)
  3. Проектирование веб-API: лучшие практики создания современных приложений (Арно Лоре)
  4. Руководство по безопасности REST API (OWASP)
  5. Модель зрелости Ричардсона: понимание уровней эволюции REST API