они публичны
API может быть реализован для частного или публичного использования. Потребители могут быть внутренними или внешними по отношению к вашей компании (партнерами или даже неизвестными, если ваш API открыт). В любом случае описание вашего ресурса API должно быть понятным для всех. Для достижения этой цели существует ряд принципов, которые необходимо соблюдать при разработке API.
Частные и общедоступные API
Частные API
Частные API предназначены для внутреннего использования. Цель — коммуникация сервисов внутри компании. Обычно для внутреннего использования мониторинг и документирование API менее важны, а ресурсы используют множество внутренних или технических имен.
Общедоступные API
Общедоступные API доступны партнерам или любому пользователю в Интернете.
Существует ряд требований, которые необходимо выполнить, прежде чем выставлять свои API для внешнего использования. Основные правила описаны ниже.
Создайте свой API
Следующие принципы могут помочь вам лучше спроектировать свои API:
Держать его просто глупо
Ваш API должен быть понятен потребителям, существует набор правил, которые помогут вам иметь простые API:
- Используйте простые слова для своихресурсов, избегайте сокращений или внутренних терминов.
- Используйте существительные вместо глаголов, таких как клиенты, заказы, транспортные средства…
- Используйте множественное число вместо единственного числа: users вместо user.
- Разработайте правильные HTTP методы: GET, POST, PUT, PATCH, HEAD и DELETE.
- Используйте коды HTTP колготок, чтобы возвращать статус в случае успеха или неудачи.
Ваш API будет иметь v2
Жизненный цикл API очень важен при разработке интерфейса. Я советую вам:
- Поддерживать 2 версии API, не более.
- Заблаговременно предупреждайте пользователей API, когда планируется выпуск новой версии и когда их фактическая версия будет устарела, чтобы у них было время перейти на более новую версию.
- Внесите в свою документацию подробные изменения.
- Создайте песочницу, чтобы ваши потребители могли протестировать ваши API, прежде чем использовать их в рабочей среде.
Защитите свой API
Нам необходимо обеспечить безопасный доступ к ресурсам, выставленным в Интернете. Советую использовать самые распространенные решения (OAuth2, OIDC, API_KEY…) и добавить мониторинг доступа.
Документируйте свой API
API должны быть хорошо документированы. Это можно сделать с помощью того, что мы называем «Портал разработчика». На портале разработчиков мы можем найти каталог API, жизненный цикл, информацию о ценах (если ваши API платные), как связаться с производителем API и технические требования для использования API (API_KEY, аутентификация…). Портал разработчиков Twitter, например:
https://developer.twitter.com/en/docs/twitter-api
Управление API
Диспетчер API — это набор технических решений, которые помогают вам управлять своими API и раскрывать их. Общие функции, предоставляемые APIM:
- Шлюз: точка входа во все API
- Портал разработчиков: регистрация потребителей, документация, поддержка…
- Портал API: мониторинг, квоты, отчетность…
- Безопасность: аутентификация и авторизация
Примеры решений по управлению API на рынке: Apigee, Kong, Axway и др.
Всегда проектируйте свои API так, как если бы они были общедоступными
Когда вы разрабатываете свой API, даже частный, я советую вам всегда помнить, что однажды вы можете открыть свой сервис в Интернете. Вместо того, чтобы разрабатывать API для команды рядом с вами, создавайте его так, как будто им будут пользоваться неизвестные потребители. Ваши API улучшат качество и удобство сопровождения:
- Ресурсы будут лучше названы и понятны каждому.
- Вы включите управление версиями в свой дизайн, чтобы вам было легче соответствовать новым требованиям.
- Вы будете поддерживать свою документацию в актуальном состоянии, новые потребители.
- Это повысит безопасность ваших ресурсов.
Еда на вынос
Чтобы понять реальное влияние разработки частных API как общедоступных, вы можете взглянуть на то, что мы называем «мандатом API Безоса». Это прорыв в индустрии API.
