Перейти к основному содержимому

Лучшие практики проектирования API

API Design

В названиях путей к эндпоинтам используем имена, а не глаголы​

В методах HTTP-запроса уже содержится глагол. Ставить глаголы в названиях путей к конечной точке API не добавит никакой ценной информации.

  • Правильно: GET /v1/articles/{id}
  • Неправильно: POST /v1/get-article/{id}

Коллекции называем существительными во множественном числе​

Соблюдаем единообразие интерфейсов.

  • Правильно: GET /v1/articles/{id}
  • Неправильно: GET /v1/article/{id}

Иерархия сущностей должны отражаться в URL​

Если есть сущности, которые состоят из других сущностей, то нужно показать это в адресе ресурса. Это поможет понять структуру и связи между сущностями.

  • Правильно: GET /v1/articles/{id}/comments
  • Неправильно: GET /v1/article-comments?article_id={id}

Используем подходящие коды ошибок​

Существует много кодов HTTP. Важно, чтобы HTTP-код был верным.

  • Возвращать код 200, когда всё ОК и запрос отработал без ошибок.

  • "Пятисотить" только в случае аварийной ситуации/багов/исключений на нашей стороне.

  • По коду HTTP должно быть понятно состояние запроса, например, 404 – не найдено.

  • Неправильно:

    • Возвращать код 200 с информацией об ошибке в body.
    • Возвращать код 5xx, когда получена стандартная ошибка.
    • Всегда возвращать коды 400 или 500 без использования разнообразия.

Используем уместные HTTP-методы​

  • GET – получение данных о ресурсах.
  • POST – создание новых ресурсов.
  • PUT – полное обновление существующих ресурсов.
  • PATCH – обновление только определённых полей уже существующих ресурсов.
  • DELETE – удаление ресурса.

Используем пагинацию/оффсеты для массивных данных​

Если у нас есть метод, который возвращает список всех заказов, то не стоит вытягивать все данные за один раз. Лучше добавить пагинацию или оффсет, чтобы извлекать часть данных и не создавать лишнюю нагрузку.

Кэшируем данные для улучшения производительности​

В некоторых случаях может быть полезно сохранять в быстрой памяти (например, в Redis) данные вместо того, чтобы каждый раз выполнять сложные запросы к БД или внешним системам.

Применяем версионирование API​

У нас должны быть различные версии API на тот случай, если мы вносим в них изменения, которые могут нарушить работу клиента. Так мы можем соблюсти требование обратной совместимости.

  • Пример:
    • Создать новую версию API метода POST /v2/articles и добавить новый параметр туда, а POST /v1/articles оставить без изменений.
    • Не выкатывать изменения сразу на POST /articles без версионирования.

Ещё несколько рекомендаций​

  • Не передавать токены аутентификации в URL или в body.
  • Передавать токены аутентификации в заголовках.
  • Использовать kebab-case для URL и camelCase для параметров.
  • Использовать даты в формате ISO 8601.
  • Возвращать созданные ресурсы после POST.
  • Используйте PUT, если нужно заменить ресурс целиком. Используйте PATCH, если нужно изменить в ресурсе лишь часть данных.

Подборка материалов​

Статьи​

  1. Наилучшие практики создания REST API — Habr
  2. RESTful web API design — Microsoft
  3. Как проектировать веб-API: 7 самых важных вопросов — Babok School
  4. Best Practices, которые стоит использовать при проектировании REST API — советы от ведущего системного аналитика
  5. Как построить REST-like API в крупном проекте — опыт от ЮMoney
  6. Рекомендации по REST API — примеры — Habr

Видео​

  1. Проектирование API в терминах RESTful — доклад Алексея Романова на конференции Analyst Days EA #1
  2. Паттерны проектирования API — доклад Андрея Буракова из VK Pay на конференции Analyst Days-12
  3. Как аналитику спроектировать свой REST API — демо-занятие курса от OTUS

Книги​

  1. Джей Гивакс. Паттерны проектирования API
  2. Арно Лоре. Проектирование веб-API
  3. Сергей Константинов. API