Проектирование и разработка API
Мы проектируем и создаём API, с которыми удобно интегрироваться: с понятными контрактами, разумным версионированием, настоящей документацией и встроенной безопасностью. API, который обслуживает ваши собственные приложения или сторонние интеграции, сам по себе является продуктом, и мы относимся к нему именно так.
API как продукт, а не как побочная задача
Хороший API последователен, хорошо документирован и его трудно использовать неправильно. От этого зависит, займёт интеграция полдня или месяц. Мы сначала проектируем контракт, как следует его защищаем и документируем так, чтобы другие могли работать с ним, не гадая.
- Проектирование и реализация REST и gRPC API
- Контракт-first проектирование с документацией OpenAPI
- Аутентификация и авторизация, сделанные правильно (OAuth, токены, области)
- Версионирование, ограничение частоты и пагинация
- Вебхуки и событийно-управляемая интеграция
- Интеграция и оркестрация сторонних API, от которых вы зависите
Как мы строим API
Сначала контракт, безопасность по умолчанию и документация по ходу работы. На такой API могут положиться все, кто его использует, включая вас самих через год.
- 1
Сначала контракт
Проектируем поверхность API и согласуем контракт (ресурсы, методы, ошибки) до того, как писать реализацию.
- 2
Сборка и защита
Идиоматичная реализация на Go или Node.js, с аутентификацией, авторизацией и валидацией ввода, встроенными с самого начала.
- 3
Документирование
Точная документация OpenAPI, генерируемая рядом с кодом, так что документы никогда не расходятся с реальностью.
- 4
Тестирование и защита
Контрактные и интеграционные тесты, ограничение частоты запросов и проверка безопасности. Чаще всего API подводит именно контроль доступа.
- 5
Версионирование и эксплуатация
Стратегия версионирования, которая не сломает существующих потребителей, плюс метрики и логирование, чтобы видеть, как он используется.
Что вы получаете
API, на который другие могут уверенно опираться: документированный, защищённый и версионируемый.
- Документированный REST или gRPC API
- Документация OpenAPI / схемы, которая остаётся синхронной с кодом
- Аутентификация и авторизация с правильным ограничением областей
- Ограничение частоты, пагинация и стратегия версионирования
- Контрактные и интеграционные тесты, плюс обзор безопасности
- Метрики, логирование и передача для вашей команды
Инструментарий API
Версионирование, документация и контрактные тесты: именно эта дисциплина позволяет другим полагаться на ваш API.
Вопросы по разработке API
REST или gRPC?
REST подходит по умолчанию для публичных API и API для браузера: он универсален, кешируется и прост в использовании. gRPC хорош для внутреннего трафика между сервисами, где нужны строгая типизация, потоковая передача и меньшие накладные расходы. Многие системы используют оба. Мы выбираем исходя из того, кто и как будет пользоваться API, а не из моды.
Будет ли API как следует документирован?
Да, и документация генерируется из контракта, поэтому она не может незаметно разойтись с реализацией. Пользователи API получают точную документацию OpenAPI, которую можно читать, пробовать и по которой можно генерировать клиенты. Именно это превращает месячную интеграцию в работу на полдня.
Как вы защищаете API?
Аутентификацию и авторизацию мы закладываем с самого начала: правильная работа с токенами, разрешения с ограниченной областью действия и проверка входных данных на каждом эндпоинте. Ошибки в контроле доступа остаются самой распространённой уязвимостью API, поэтому мы проверяем авторизацию явно, а не надеемся на фреймворк.
Можете ли вы интегрировать сторонние API, на которые мы опираемся?
Да. Мы интегрируем и связываем между собой внешние API, от которых зависит ваш продукт, например платежи, идентификацию и обмен сообщениями. Добавляем разумные повторы, обработку ошибок и чистую абстракцию, чтобы смена поставщика не затронула всю кодовую базу.