Listen IT

🏆 Лучшие практики проектирования 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 #интеграции #проектирование