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

В названиях путей к эндпоинтам используем имена, а не глаголы
В метода HTTP-запроса уже содержится глагол. Ставить глаголы в названиях путей к конечной точке API не добавит никакой ценной информации
✅ GET /v1/articles/{id}
❌ POST /v1/get-article/{id}

Коллекции называем существительными во множественном числе
Соблюдаем единообразие интерфейсов (принцип REST №4)
✅ 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. Это поможет клиенту, например, узнать сгенерированный ID и не делать лишних запросов

✅ Используйте 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 (скачать .pptx)
3. Как аналитику спроектировать свой REST API — демо-занятие курса от OTUS

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

#api #интеграции #проектирование