Чек-лист для проектирования API
За 5 лет, что я проектирую API, вывела для себя шесть базовых принципов, которых стараюсь придерживаться:
Проектировать для потребителя
Ориентироваться на потребности клиентов API, а не на простоту реализации или устройство базы данных. Об этом, кстати, подробно написано в отличной книге Лоре Арно “Проектирование веб-API”.
Учитывать интересы всех клиентов. Не забывать, что могут появиться новые клиенты.
Сложную логику реализовывать на сервере. Искать баланс между универсальностью API и нагрузкой на клиента, исходя из реалий проекта.
Проектировать понятные API-схемы
Наименования и структуры должны быть максимально прозрачными, ясными и лаконичными.
Избегать обобщающих наименований, типа “flag”. Описывать в названии, какой бизнес-смысл несет этот параметр или метод. Например, флаг с признаком пустой упаковки можно назвать “isEmpty”.
Человек при прочтении схемы должен без дополнительной документации понять, зачем нужен этот API и что он делает.
Отдавать адекватные текстовые коды ошибок, из которых будет однозначно понятно, что поправить в запросе для успешного его выполнения. Например, отдавать не 400 BAD_REQUEST, а 400 PRODUCT_NOT_FOUND.
Принять конвенции и придерживаться их
Использовать везде либо snake_case, либо camelCase, либо kebab-case, не менять правила от метода к методу.
Стандартизировать формат ошибок - во всех методах отдавать их в одинаковой структуре.
Если это HTTP, то зафиксировать, в каких случаях какие коды ответов будут возвращаться. Например, иногда возвращается всегда 200, а потребители ориентируются только на тело ответа.
Договориться о формате версионирования API.
Стандартизировать типы данных: формат дат, UUID и пр.
Думать о безопасности, производительности и надежности
Использовать аутентификацию, авторизацию и ACL. Разграничивать доступ на уровне конкретных методов и даже параметров.
Оценивать количество запросов и объем ответов.
Индексировать БД по тем полям, по которым собираются выборки данных для API.
Использовать асинхронное взаимодействие, если задача на сервере выполняется ощутимое количество времени.
Делать обратную совместимость везде, где это возможно.
Документировать
Сначала писать документацию, а только потом разрабатывать. Такой подход минимизирует количество ошибок и проблем с API.
Помечать изменения тегами задач и, при необходимости, цветом.
Описывать логику работы методов/топиков/очередей. При необходимости добавлять диаграммы последовательности и маппинги данных.
Мониторить и анализировать
Понимать, какие методы как часто вызываются и как быстро работают. Как быстро обрабатываются сообщения в очередях и топиках, какое их количество и размеры. Это важно для принятия решений о дальнейших доработках API.
Смотреть в консоли разработчика на проде, как быстро отрабатывают те или иные запросы и т.д.
По возможности настраивать системы мониторинга и алертинга. Это помогает прогнозировать рост нагрузки и отслеживать эффективность системы.
У каждого API‑проектировщика со временем появляется свой набор правил. Было бы интересно сравнить — добавляйте свои пункты в комментариях.
Другие мои материалы можно почитать в телеграм-канале breakfront.