Как стать автором
Обновить

Чек-лист для проектирования API

За 5 лет, что я проектирую API, вывела для себя шесть базовых принципов, которых стараюсь придерживаться:

  1. Проектировать для потребителя

    • Ориентироваться на потребности клиентов API, а не на простоту реализации или устройство базы данных. Об этом, кстати, подробно написано в отличной книге Лоре Арно “Проектирование веб-API”.

    • Учитывать интересы всех клиентов. Не забывать, что могут появиться новые клиенты.

    • Сложную логику реализовывать на сервере. Искать баланс между универсальностью API и нагрузкой на клиента, исходя из реалий проекта.

  2. Проектировать понятные API-схемы

    • Наименования и структуры должны быть максимально прозрачными, ясными и лаконичными.

    • Избегать обобщающих наименований, типа “flag”. Описывать в названии, какой бизнес-смысл несет этот параметр или метод. Например, флаг с признаком пустой упаковки можно назвать “isEmpty”.

    • Человек при прочтении схемы должен без дополнительной документации понять, зачем нужен этот API и что он делает.

    • Отдавать адекватные текстовые коды ошибок, из которых будет однозначно понятно, что поправить в запросе для успешного его выполнения. Например, отдавать не 400 BAD_REQUEST, а 400 PRODUCT_NOT_FOUND.

  3. Принять конвенции и придерживаться их

    • Использовать везде либо snake_case, либо camelCase, либо kebab-case, не менять правила от метода к методу.

    • Стандартизировать формат ошибок - во всех методах отдавать их в одинаковой структуре.

    • Если это HTTP, то зафиксировать, в каких случаях какие коды ответов будут возвращаться. Например, иногда возвращается всегда 200, а потребители ориентируются только на тело ответа.

    • Договориться о формате версионирования API.

    • Стандартизировать типы данных: формат дат, UUID и пр.

  4. Думать о безопасности, производительности и надежности

    • Использовать аутентификацию, авторизацию и ACL. Разграничивать доступ на уровне конкретных методов и даже параметров.

    • Оценивать количество запросов и объем ответов.

    • Индексировать БД по тем полям, по которым собираются выборки данных для API.

    • Использовать асинхронное взаимодействие, если задача на сервере выполняется ощутимое количество времени.

    • Делать обратную совместимость везде, где это возможно.

  5. Документировать

    • Сначала писать документацию, а только потом разрабатывать. Такой подход минимизирует количество ошибок и проблем с API.

    • Помечать изменения тегами задач и, при необходимости, цветом.

    • Описывать логику работы методов/топиков/очередей. При необходимости добавлять диаграммы последовательности и маппинги данных.

  6. Мониторить и анализировать

    • Понимать, какие методы как часто вызываются и как быстро работают. Как быстро обрабатываются сообщения в очередях и топиках, какое их количество и размеры. Это важно для принятия решений о дальнейших доработках API.

    • Смотреть в консоли разработчика на проде, как быстро отрабатывают те или иные запросы и т.д.

    • По возможности настраивать системы мониторинга и алертинга. Это помогает прогнозировать рост нагрузки и отслеживать эффективность системы.

У каждого API‑проектировщика со временем появляется свой набор правил. Было бы интересно сравнить — добавляйте свои пункты в комментариях.

Другие мои материалы можно почитать в телеграм-канале breakfront.

Теги:
0
Комментарии0

Публикации

Ближайшие события