Недавно у меня была возможность встретиться с руководителями компании Postman и другими лидерами отрасли API. Это был пугающий, волнующий и унизительный опыт. Мы говорили обо всем: от опыта разработчиков до жизненного цикла API, от разработки API-first до даже будущего ландшафта API.
Это было потрясающе.
Не секрет, что я страстно люблю две вещи: бессерверные технологии и API. Находиться среди самых увлеченных API-руководителей было очень интересно.
Когда мы начали говорить об API-первой разработке, кое-что привлекло мое внимание. Я много лет говорил о том, что я API-first, думая, что я это делаю, но когда мы заговорили о нюансах реализации, я быстро понял, что то, что я думал, было ложью.
Ладно, не совсем ложь, но у меня сложилось неверное впечатление. Я обнаружил, что у вас может быть такое же неправильное впечатление, как и у меня.
Так что давайте поговорим об этом и выясним, действительно ли вы разрабатываете API-first или только думаете, что разрабатываете.
Что такое API-First?
Я никогда не смогу объяснить это так хорошо, как это делает Кин Лейн из Postman. Он может объяснить все аспекты того, что такое API-first, в 13 пунктах.
На высоком уровне, API-first означает, что вы отдаете приоритет своим API как своему продукту. Вы вкладываете целенаправленную стратегию в их разработку, внедрение, безопасность и открываемость.
Хотя эти характеристики могут показаться очевидными компонентами, на которых следует сосредоточиться, на самом деле отличительной чертой является контекст.
Традиционно компании, которые уделяют особое внимание дизайну, безопасности, открываемости и т. д., создают приложения. Имеется в виду приложение полного стека, которое они отправляют клиентам. По своей сути это не проблема, но это не API-first.
В API-first контекст — это ваш API. Это механизм, используемый для манипулирования вашей системой. Вы делаете на нем акцент, чтобы интеграторы имели те же ключи к системе, что и вы (за некоторыми исключениями).
API-first — это переход от создания пользовательских приложений для ваших потребителей к предоставлению им возможности создавать их самостоятельно.
Снимите с себя хлопоты по созданию и поддержке пользовательских приложений. Обеспечьте значимый опыт разработчика для ваших потребителей, и они будут использовать вашу систему так, как вы даже не ожидали.
Если вы думаете, что уже делаете все это, то я тоже. Давайте обсудим, что все это значит, когда речь идет о повседневной работе.
Что это значит?
При внедрении API-первой разработки на практике, детали действительно проявляются в стандартных изменениях процесса, которые вам придется сделать. Нужно изменить не только порядок событий, но и усилия, которые прилагаются для структурирования работы.
Определение работы
Первая фаза API-first — это определение. Фаза определения при разработке API включает в себя не только разработчиков. В нем участвуют бизнес-подразделения и продуктовые подразделения, работающие вместе с разработчиками над четким определением функциональности API.
Какие бизнес-проблемы вы пытаетесь решить? Какие объекты данных задействованы? Каков жизненный цикл каждой из этих сущностей?
Более подробные вопросы, такие как PATCH или PUT, как структурировать формат конечной точки и как обрабатывать пейджинг, уже должны быть отвечены на вопросы и определены в вашей модели управления.
Если у вас еще нет модели управления, это будет хорошим началом. Если вы не знаете, с чего начать построение модели управления, вы можете использовать в качестве основы коллекцию правил управления Postman Open Technologies.
Правила управления предназначены для итераций. Поэтому найдите то, что вам нравится, внесите изменения и рассмотрите все новое, что появится. Главное, чтобы вы с чего-то начали.
Такой подход к работе одинаков, независимо от того, создаете ли вы совершенно новый API с нуля или добавляете функциональность к уже существующему. Первым шагом всегда является сбор группы для обсуждения бизнес-целей и четкого определения проблемной области.
Разделение историй
Когда я только начинал работу над своей версией API-first, у меня сложилось впечатление, что это означает, что все, что мне нужно делать, это сначала работать над историями о конечных точках.
API-first не означает простое выполнение историй API перед историями пользовательского интерфейса.
На самом деле, при API-first разработке вполне возможно работать над пользовательским интерфейсом и реализацией API одновременно.
Первый набор историй — это создание спецификации API, которая включает в себя конечные точки, схемы и примеры запросов и ответов. После этого вы можете создать макет сервера, который будет возвращать поддельные данные в ожидаемом формате.
С учетом этого можно приступать к разработке пользовательского интерфейса, пока вы начинаете реальную реализацию вашего API. Помните, что при таком подходе к разработке вы относитесь к API как к своему продукту. Любой пользовательский интерфейс, который вы создаете на его основе, является добавленной стоимостью.
Тестирование и мониторинг
Устойчивость и прочность являются ключевыми показателями успеха при разработке API. Для проверки этих компонентов ваши API должны иметь множество различных тестов, которые по-разному нагружают их.
- Тесты контракта — проверяют, что API принимает и возвращает правильную схему в запросе и ответе.
- Тесты производительности — проверяют, что ваш API возвращает ответ за ожидаемое время.
- Тесты безопасности — определяют, имеет ли ваш API правильный контроль доступа к данным и конечным точкам.
- сквозные тесты — запуск рабочих процессов через систему, чтобы убедиться, что различные бизнес-цели могут быть выполнены.
Вы должны не только иметь каждый из этих тестов для вашего API, но и иметь способ убедиться, что они не выдают ошибок. Используйте любой вид APM, например DataDog, New Relic или даже Postman, чтобы отслеживать успешность тестов и уведомлять соответствующую команду, когда что-то перестает работать.
Включение автоматизированных API-тестов в определение «сделано» является показателем того, что вы делаете API-first правильно.
Если вы не проводите такие тесты в рамках цикла разработки, вам необходимо начать. Тесты контрактов и тесты производительности могут генерироваться динамически. Но для сквозных тестов необходимо приложить некоторые сознательные ручные усилия, чтобы заставить их выполнять реальные сценарии.
Чем лучше вы сможете автоматизировать сценарии, которые выполняют ваши потребители, тем выше вероятность того, что вы не будете вносить изменения в систему.
Сделать ваш API доступным для обнаружения
Когда я руководил командой разработчиков облачных решений, мы завершали работу над новым API и переходили к следующей истории. Другие команды в моей компании даже не подозревали о существовании нового API, а если бы они узнали о нем, то не имели бы понятия, как его найти и интегрировать с ним.
Черт возьми, даже разработчикам из моей команды было бы трудно найти подробную информацию об API.
Это потому, что мы не делали наши API доступными для поиска.
Представьте, что вы продаете свой дом, и ваш риэлтор выставляет его на продажу онлайн на своем сайте. Они не вывешивают табличку во дворе или не рекламируют его в социальных сетях. Скорее всего, ваш дом не будет продан в разумные сроки. Это происходит потому, что его невозможно найти.
Как покупатели должны найти ваш дом? Должны ли они знать, что нужно заглянуть на сайт вашего риэлтора? Этого не произойдет.
То же самое относится и к созданию API. Вы должны разместить его в месте, которое люди знают, где искать, а затем рекламировать его.
Если людям приходится спрашивать, где найти документацию по вашему API или какие API у вас есть в наличии, считайте это тревожным сигналом, что вы не очень хорошо справляетесь с открываемостью.
Postman имеет как публичную, так и частную сеть, чтобы облегчить вам внешний и внутренний обмен вашими API.
Заключение
API-first означает отношение к API как к своему продукту.
Для этого необходимо изменить фокус и акценты. Вы не будете принимать дизайнерские решения, основываясь на том, куда, по вашему мнению, должен нажать пользователь. Вместо этого вы думаете о том, как легко позволить интеграторам соединять запросы в цепочку для выполнения бизнес-сценария.
Работайте в рамках всей организации над созданием спецификации API в осмысленном виде. Итерируйте дизайн, пока не будете им довольны. Не начинайте писать код, пока спецификация не будет завершена.
Уделите повышенное внимание возможностям мониторинга. Измените свое определение понятия «готово». Не принимайте ничего, что нужно тестировать вручную при каждом изменении. Автоматизируйте тесты и уведомляйте команду о поломке.
Пусть весь мир знает, что вы сделали. Разместите свои API в сети, чтобы их можно было легко обнаружить. Не полагайтесь на сарафанное радио и племенные знания, когда ваш API готов. Ваша команда разработчиков не масштабируется. Они не могут работать над новыми API и пропагандировать уже готовые API.
Такой подход к разработке как будто переворачивает стандартную разработку с ног на голову. И это хорошо.
Срыв стимулирует инновации.
Переключая свою организацию на API и опыт разработчиков, вы открываете двери для того, о чем даже не подозревали. Люди креативны. Если вы дадите им ключи от вашего API, они заставят его делать то, что вы и представить себе не могли. Именно для этого мы все здесь и собрались.
Счастливого кодинга!