Привет всем!
Сегодня мы хотели предложить вам перевод программной статьи небезызвестного Майка Амундсена, ведущего архитектора из API Academy. В этом сравнительно небольшом тексте Майк толково рассказывает, зачем требуется уделять особое внимание разработке API, и как API делаются правильно.
За время работы преподавателем в API Academy мне довелось объехать весь мир, встречаясь с удивительными людьми. Они работают над ошеломительными проектами во всевозможных компаниях – от молодых стартапов до состоявшихся глобальных предприятий. Невероятно, но, где бы я ни был и с кем бы ни говорил, в наших беседах всплывало множество общих идей, приемов и впечатлений. Три наиболее общих – это микросервисы, API и культура инноваций. Все три внедряются ради ускорения цифрового преобразования организации.
Эта статья – вторая в серии из трех публикаций. Здесь я расскажу о том, чему мы учим в нашей API-академии в контексте трех этих мощных трендов, а также опишу некоторые приемы, которые помогут вашей компании перейти от громких слов к реальным преобразованиям. В предыдущей статье я уделил особое внимание важности микросервисов и остановился на трех вещах, которые вам по силам уже сегодня: 1) переход к непрерывной доставке, 2) обеспечение подготовленных развертываний и 3) сокращение очереди «в работе» ради сокращения времени до выхода продукта на рынок. Три этих важнейших привычки помогут вашей организации на полную мощность использовать преимущества микросервисов.
API обеспечивают многоканальную доставку
Многие компании используют микросервисы, стремясь инкапсулировать ключевые возможности своей организации именно так, чтобы обеспечить их масштабируемость и надежность. Микросервисы соответствуют важным функциональным элементам IT-составляющей вашей компании. Но это только полдела. Также необходимо придумать, как предоставлять эти возможности, чтобы с их помощью было удобно решать актуальные вызовы, встающие перед вашим бизнесом. Именно здесь в игру и вступают API.
API — интерфейсы программирования приложений — играют для машины ту же роль, что и графический интерфейс – для пользователей информационных систем вашей компании. Зачастую API используются для смешивания различных возможностей в согласованное и доступное решение. Например, в вашей компании могут применяться сервисы для обработки операций, связанных с клиентами, учетными записями и продажами. Каждый из этих сервисов тщательно проектировался, программировался, тестировался, после чего был выпущен и встроен в инфраструктуру вашей компании; сервис обеспечивает функционал, критичный для вашего бизнеса. Однажды вам понадобится создать новое решение для введения пользователей в курс дела – и это решение должно работать на самых разных устройствах и платформах. Итак, начинаем использовать API на полную мощность.
Единый API, заточенный под решения – например, API для ознакомления пользователей с системой — можно спроектировать так, чтобы на поверхность выходили важнейшие взаимодействия и потоки задач, критичные именно на этапе такого ознакомления. Здесь нам пригодится такой API, который позволяет смешивать различные функциональные элементы, касающиеся клиентов, учетных записей и продаж, в безопасные, мощные и доступные пользовательские интерфейсы для самых разных целевых аудиторий в рамках вашей компании. Например, продажники могут заходить в систему из браузера, офисные админы – из приложений для ПК, а потенциальные клиенты – со смартфонов и планшетов.
Можно сказать, что API – это своеобразный «клей», удерживающий элементы программы вместе, слой-посредник, через который взаимодействуют ваши внутренние сервисы и внешние потребители сервисов. Именно API – это средство для распределения ключевого функционала в таком виде, чтобы им могли пользоваться потребители сервисов, чья задача – создавать важные механизмы взаимодействия с пользователем на самых разных аппаратных платформах. В число таких потребителей могут входить другие команды, работающие у вас в офисе, коллеги, с которыми вы общаетесь удаленно, ключевые бизнес-партнеры или даже удаленные сотрудники, занимающиеся разработкой клиентской части или дизайном.
Дизайн-мышление и API
В большинстве компаний известно, как важно уделять время на разработку пользовательского интерфейса для своих приложений. Потому что известно, что хороший дизайн нравится пользователям, повышает лояльность к бренду и позволяет продвигать новый бизнес. В то же время, некачественно проработанный дизайн интерфейса может раздражать клиентов, вредить бренду, сокращать выручку и отбирать возможности. То же справедливо и для проектирования API.
Если API сделан плохо, то разработчикам будет сложно его понимать, из-за этого они могут внести ошибки в систему, и спровоцировать ненужные расходы на исправление багов и модификацию инфраструктуры. Однако, если API сработан хорошо, то и сотруднику легче эффективно с ним работать. Сокращается время, необходимое на создание стабильного решения, команда даже получает стимул выдавать свежие, инновационные решения, которые помогли бы клиентам и коллегам. Проектирование API – настолько важный участок работы, что Вернер Фогельс, главный технический директор Amazon, даже сказал:
Именно качественные API помогают привлечь партнеров в вашу цифровую экосистему и упрощают внутрикорпоративные преобразования вашего бизнеса. Умение потратить время, чтобы все сделать правильно, причем, в долгосрочной перспективе – важный навык, который мы прослеживаем как раз у тех компаний, которые научились на полную мощность задействовать свои API.
Важнейший совет по проектированию API
Очень важно сделать API правильно – и на то есть много причин. После релиза откатить API обратно невозможно. Когда клиенты и ключевые бизнес-структуры зависят от вашего API, изменение зависимости может повредить другие элементы системы, сломать важный функционал и обнулить ваши вложения и потраченное время. Внедряя программу API, необходимо держать в уме и другие важные вещи. Упомяну лишь некоторые.
Канонического API не существует
Ошибочно пытаться «заранее» выбрать канонический дизайн API для всей вашей компании. Просто пытаться внедрять некоторые объекты и модели данных в масштабах всего предприятия, то есть, стремясь создать единый API, в котором были бы учтены все без исключения аспекты вашей организации, сейчас и в будущем — скорее всего, это тупиковый путь. Гораздо лучше снабдить ваших разработчиков рекомендациями и указать ограничения, что поможет им избегать ошибок, творчески раскрываться и применять знания предметной области, чтобы создавать восхитительные API, которые понравятся как коллегам, так и партнерам.
Процесс внедрения: отсекаем все лишнее
Поскольку API – это всего лишь интерфейс, а не функционал как таковой, нужно уметь проектировать, внедрять, тестировать и развертывать API за считанные дни и недели, но не за месяцы. Мы знаем, как компании пытаются снизить риски при создании API, добиваясь, чтобы API было удобно тестировать заранее, автоматизировать процесс релиза, чтобы сами API влекли меньше издержек, а компоновать их было удобнее.
Акцент на взаимодействии, а не на интеграции
Еще один ключевой аспект, с которым в совершенстве справляются успешные компании – это умение научить команды разработчиков встраивать в API возможности взаимодействия с другими элементами уже на этапе проектирования. Такие организации разъясняют, как работать с их API, поэтому такие API не просто получаются понятными, но и легко компонуются с другими API этой компании. Нацеленность на широкое взаимодействие важнее, чем проектирование узкой и тесной интеграции.
Три вещи, которые можно сделать уже сегодня
Такая работа, как и любые важные изменения, требует времени. Однако, ждать успеха придется не долго. Расскажу о трех мерах, которые мне приходилось наблюдать в самых разных компаниях, и которые вы можете принимать уже сегодня.
Взять на вооружение собственную практику создания API
Ключевая составляющая долгосрочного успеха вашей API-программы – в том, чтобы выработать практику проектирования API, не зависящую от конкретных технологий. Убедитесь, что такая программа не будет целиком зависеть от последнего писка моды в программировании, использовании библиотек или платформ. Для этого удобнее всего опираться на парадигму «первым делом — API».
«Первым делом — API» означает, что мы сначала проектируем API, и лишь потом задумываемся о деталях его реализации. В принципе, бизнес-составляющая одинакова, независимо от того, при помощи какой технологии вы реализуете API: будь то SOAP, CRUD, REST, gRPC, GraphQL или любая другая популярная вещь. На самом деле, хорошо спроектированная программа, скорее всего, позволит сформулировать рекомендации, актуальные для разных технологических стеков, соответственно, помогая вашей команде и оценить возможную экономию, и сохранить согласованность решений на последующих версиях платформ.
Гарантируем низкие риски при создании API
Качественно спроектировав API, пора воплощать его в реальности. При этом рекомендую начинать с наброска, далее переходить к прототипу и паттерну сборки.
Наброски API – это именно «эскизы». Небольшие приблизительные «чертежи», помогающие составить впечатление о том, каким может получиться этот API «на вкус и цвет» с позиции разработчика. Набросок API должен делаться за несколько часов, а не дней. Причем, на его основе должен получаться проект, который можно показать коллегам и стейкхолдерам, чтобы первый раунд обсуждения и первые модификации обошлись практически без затрат. Мне нравится использовать для этого шаблон API от Apiary. В нем используется простой язык разметки, позволяющий смоделировать рабочий сервер API за считанные минуты. Конкретный инструмент не так важен, важна практика. Наброски помогают вам выполнить дешевые исследования, и только потом приступать к подготовке полноценного API.
Я заметил, что при прототипировании популярны такие инструменты как Swagger/OpenAPI. Прототипы — это значительно более проработанные модели вашего конечного продукта. Они подобны декорациям к фильму. Если не присматриваться – видишь практически реальную сцену! Команда должна уметь подготовить подробный прототип всего за несколько дней. Такой прототип должен свободно подключаться к тестовому инструментарию, службам виртуализации и другим элементам платформы, чтобы вы могли непосредственно наблюдать, как он взаимодействует с вашей системой. Прототипы нужны для того, чтобы их тестировать. Они – ваш последний рубеж обороны перед тем как придется тратить деньги на создание реального рабочего API.
Здесь этап сборки завершается. Далее мы должны сформулировать рабочий план, установить дедлайны и приступать к превращению прототипа в продукт. Набросок и прототип требовались нам, чтобы проработать детали, выявить баги, т.д. Сам по себе процесс сборки не так интересен. Просто нужно каждый день показывать готовый результат, шаг за шагом воплощать API, пока работа не будет готова. Многие компании стремятся к тому, чтобы на сборку API уходило не более 90 дней.
Три кита управления API
Наконец, если рассмотреть ситуацию шире, чем на уровне проектирования и реализации отдельно взятого API, в организации нужно придерживаться жизнеспособной программы работы с API и применять общие рекомендации по разработке API, которые будут известны всем командам. Внятная регламентация позволяет контролировать разработку API в масштабах всего предприятия, не вдаваясь при этом в излишний надзор над деталями реализации.
Эрик Уайлд, мой коллега из API Academy, подчеркивает, как важно «управлять ландшафтом ваших API», то есть, регламентировать три ключевых элемента программы API: протоколы, форматы, терминологию.
Регламентация протоколов – это четкие указания, какие протоколы уровня приложений должна поддерживать команда разработчиков API, готовя новые релизы. В большинстве компаний считается, что все новые API должны поддерживать HTTP. Некоторые также указывают и другие, необязательные протоколы, например, MQTT, Thrift и другие двоичные протоколы. Здесь наиболее важно заранее сообщить всем командам: «Если вы хотите гарантировать интероперабельность ваших API в будущем, то должны использовать эти протоколы». Для выполнения этого правила желательно использовать конвейер непрерывной доставки.
Регламентация форматов означает, что нужно условиться, в каких форматах данные будут пересылаться между сервисами. Практически все браузеры ожидают отклика в HTML-формате – точно так и на уровне вашего API нужно определиться, в каком формате он будет взаимодействовать со всей экосистемой. В большинстве компаний предпочитают простые форматы, например, JSON, XML или CSV, но в их моделях сообщений недостает ключевых метаданных, в частности, имен объектов, ссылок и форм ввода – а они необходимы для долгосрочных взаимодействий. С другой стороны, мне известны и такие компании, в которых используются более продвинутые форматы, например, HAL, Siren и Collection+JSON для API на базе HTTP. Для бинарных взаимодействий между сервисами многие организации берут за основу protobuf и подобные форматы. Независимо от того, какой формат вы выберете, важно проверить его в вашем сборочном конвейере, убедившись таким образом, что в продакшен поступают лишь API, полностью соответствующие регламентации.
Третий кит управления API – это терминология. В данном случае речь идет о контроле над названиями точек данных и идентификаторов действий, используемых при обмене сообщениями между сервисами. Придерживаясь терминологии, организация может не сомневаться, что новые сервисы будут нормально восприняты уже существующими. Вспоминая «общий язык», предложенный Эриком Эвансом для предметно-ориентированного проектирования (DDD), отмечу, что выбранная вами терминология нужна для того, чтобы рассуждать о наиболее критичных бизнес-операция. Должно быть непросто выпустить в продакшен такой сервис, в котором используются «совершенно новые» названия полей данных и идентификаторов действий. Напротив, элементы сборочного конвейера должны проходить проверку на соответствие общей терминологии, принятой во всей компании, а выбивающиеся из этой терминологии API не должны попадать в продакшен.
Усвоив эти принципы: «Первым делом — API», «эскиз-прототип-сборка» и «три кита управления API», ваша команда сможет использовать свои API на полную мощность, ничуть не рискуя их стабильностью во время выполнения.
Сегодня мы хотели предложить вам перевод программной статьи небезызвестного Майка Амундсена, ведущего архитектора из API Academy. В этом сравнительно небольшом тексте Майк толково рассказывает, зачем требуется уделять особое внимание разработке API, и как API делаются правильно.
За время работы преподавателем в API Academy мне довелось объехать весь мир, встречаясь с удивительными людьми. Они работают над ошеломительными проектами во всевозможных компаниях – от молодых стартапов до состоявшихся глобальных предприятий. Невероятно, но, где бы я ни был и с кем бы ни говорил, в наших беседах всплывало множество общих идей, приемов и впечатлений. Три наиболее общих – это микросервисы, API и культура инноваций. Все три внедряются ради ускорения цифрового преобразования организации.
Эта статья – вторая в серии из трех публикаций. Здесь я расскажу о том, чему мы учим в нашей API-академии в контексте трех этих мощных трендов, а также опишу некоторые приемы, которые помогут вашей компании перейти от громких слов к реальным преобразованиям. В предыдущей статье я уделил особое внимание важности микросервисов и остановился на трех вещах, которые вам по силам уже сегодня: 1) переход к непрерывной доставке, 2) обеспечение подготовленных развертываний и 3) сокращение очереди «в работе» ради сокращения времени до выхода продукта на рынок. Три этих важнейших привычки помогут вашей организации на полную мощность использовать преимущества микросервисов.
API обеспечивают многоканальную доставку
Многие компании используют микросервисы, стремясь инкапсулировать ключевые возможности своей организации именно так, чтобы обеспечить их масштабируемость и надежность. Микросервисы соответствуют важным функциональным элементам IT-составляющей вашей компании. Но это только полдела. Также необходимо придумать, как предоставлять эти возможности, чтобы с их помощью было удобно решать актуальные вызовы, встающие перед вашим бизнесом. Именно здесь в игру и вступают API.
API — интерфейсы программирования приложений — играют для машины ту же роль, что и графический интерфейс – для пользователей информационных систем вашей компании. Зачастую API используются для смешивания различных возможностей в согласованное и доступное решение. Например, в вашей компании могут применяться сервисы для обработки операций, связанных с клиентами, учетными записями и продажами. Каждый из этих сервисов тщательно проектировался, программировался, тестировался, после чего был выпущен и встроен в инфраструктуру вашей компании; сервис обеспечивает функционал, критичный для вашего бизнеса. Однажды вам понадобится создать новое решение для введения пользователей в курс дела – и это решение должно работать на самых разных устройствах и платформах. Итак, начинаем использовать API на полную мощность.
Единый API, заточенный под решения – например, API для ознакомления пользователей с системой — можно спроектировать так, чтобы на поверхность выходили важнейшие взаимодействия и потоки задач, критичные именно на этапе такого ознакомления. Здесь нам пригодится такой API, который позволяет смешивать различные функциональные элементы, касающиеся клиентов, учетных записей и продаж, в безопасные, мощные и доступные пользовательские интерфейсы для самых разных целевых аудиторий в рамках вашей компании. Например, продажники могут заходить в систему из браузера, офисные админы – из приложений для ПК, а потенциальные клиенты – со смартфонов и планшетов.
Можно сказать, что API – это своеобразный «клей», удерживающий элементы программы вместе, слой-посредник, через который взаимодействуют ваши внутренние сервисы и внешние потребители сервисов. Именно API – это средство для распределения ключевого функционала в таком виде, чтобы им могли пользоваться потребители сервисов, чья задача – создавать важные механизмы взаимодействия с пользователем на самых разных аппаратных платформах. В число таких потребителей могут входить другие команды, работающие у вас в офисе, коллеги, с которыми вы общаетесь удаленно, ключевые бизнес-партнеры или даже удаленные сотрудники, занимающиеся разработкой клиентской части или дизайном.
Дизайн-мышление и API
В большинстве компаний известно, как важно уделять время на разработку пользовательского интерфейса для своих приложений. Потому что известно, что хороший дизайн нравится пользователям, повышает лояльность к бренду и позволяет продвигать новый бизнес. В то же время, некачественно проработанный дизайн интерфейса может раздражать клиентов, вредить бренду, сокращать выручку и отбирать возможности. То же справедливо и для проектирования API.
Если API сделан плохо, то разработчикам будет сложно его понимать, из-за этого они могут внести ошибки в систему, и спровоцировать ненужные расходы на исправление багов и модификацию инфраструктуры. Однако, если API сработан хорошо, то и сотруднику легче эффективно с ним работать. Сокращается время, необходимое на создание стабильного решения, команда даже получает стимул выдавать свежие, инновационные решения, которые помогли бы клиентам и коллегам. Проектирование API – настолько важный участок работы, что Вернер Фогельс, главный технический директор Amazon, даже сказал:
Мы сразу сознавали, что проектирование API – очень важная задача, поскольку у нас будет всего одна попытка, чтобы решить ее правильно.
Именно качественные API помогают привлечь партнеров в вашу цифровую экосистему и упрощают внутрикорпоративные преобразования вашего бизнеса. Умение потратить время, чтобы все сделать правильно, причем, в долгосрочной перспективе – важный навык, который мы прослеживаем как раз у тех компаний, которые научились на полную мощность задействовать свои API.
Важнейший совет по проектированию API
Очень важно сделать API правильно – и на то есть много причин. После релиза откатить API обратно невозможно. Когда клиенты и ключевые бизнес-структуры зависят от вашего API, изменение зависимости может повредить другие элементы системы, сломать важный функционал и обнулить ваши вложения и потраченное время. Внедряя программу API, необходимо держать в уме и другие важные вещи. Упомяну лишь некоторые.
Канонического API не существует
Ошибочно пытаться «заранее» выбрать канонический дизайн API для всей вашей компании. Просто пытаться внедрять некоторые объекты и модели данных в масштабах всего предприятия, то есть, стремясь создать единый API, в котором были бы учтены все без исключения аспекты вашей организации, сейчас и в будущем — скорее всего, это тупиковый путь. Гораздо лучше снабдить ваших разработчиков рекомендациями и указать ограничения, что поможет им избегать ошибок, творчески раскрываться и применять знания предметной области, чтобы создавать восхитительные API, которые понравятся как коллегам, так и партнерам.
Процесс внедрения: отсекаем все лишнее
Поскольку API – это всего лишь интерфейс, а не функционал как таковой, нужно уметь проектировать, внедрять, тестировать и развертывать API за считанные дни и недели, но не за месяцы. Мы знаем, как компании пытаются снизить риски при создании API, добиваясь, чтобы API было удобно тестировать заранее, автоматизировать процесс релиза, чтобы сами API влекли меньше издержек, а компоновать их было удобнее.
Акцент на взаимодействии, а не на интеграции
Еще один ключевой аспект, с которым в совершенстве справляются успешные компании – это умение научить команды разработчиков встраивать в API возможности взаимодействия с другими элементами уже на этапе проектирования. Такие организации разъясняют, как работать с их API, поэтому такие API не просто получаются понятными, но и легко компонуются с другими API этой компании. Нацеленность на широкое взаимодействие важнее, чем проектирование узкой и тесной интеграции.
Три вещи, которые можно сделать уже сегодня
Такая работа, как и любые важные изменения, требует времени. Однако, ждать успеха придется не долго. Расскажу о трех мерах, которые мне приходилось наблюдать в самых разных компаниях, и которые вы можете принимать уже сегодня.
Взять на вооружение собственную практику создания API
Ключевая составляющая долгосрочного успеха вашей API-программы – в том, чтобы выработать практику проектирования API, не зависящую от конкретных технологий. Убедитесь, что такая программа не будет целиком зависеть от последнего писка моды в программировании, использовании библиотек или платформ. Для этого удобнее всего опираться на парадигму «первым делом — API».
«Первым делом — API» означает, что мы сначала проектируем API, и лишь потом задумываемся о деталях его реализации. В принципе, бизнес-составляющая одинакова, независимо от того, при помощи какой технологии вы реализуете API: будь то SOAP, CRUD, REST, gRPC, GraphQL или любая другая популярная вещь. На самом деле, хорошо спроектированная программа, скорее всего, позволит сформулировать рекомендации, актуальные для разных технологических стеков, соответственно, помогая вашей команде и оценить возможную экономию, и сохранить согласованность решений на последующих версиях платформ.
Гарантируем низкие риски при создании API
Качественно спроектировав API, пора воплощать его в реальности. При этом рекомендую начинать с наброска, далее переходить к прототипу и паттерну сборки.
Наброски API – это именно «эскизы». Небольшие приблизительные «чертежи», помогающие составить впечатление о том, каким может получиться этот API «на вкус и цвет» с позиции разработчика. Набросок API должен делаться за несколько часов, а не дней. Причем, на его основе должен получаться проект, который можно показать коллегам и стейкхолдерам, чтобы первый раунд обсуждения и первые модификации обошлись практически без затрат. Мне нравится использовать для этого шаблон API от Apiary. В нем используется простой язык разметки, позволяющий смоделировать рабочий сервер API за считанные минуты. Конкретный инструмент не так важен, важна практика. Наброски помогают вам выполнить дешевые исследования, и только потом приступать к подготовке полноценного API.
Я заметил, что при прототипировании популярны такие инструменты как Swagger/OpenAPI. Прототипы — это значительно более проработанные модели вашего конечного продукта. Они подобны декорациям к фильму. Если не присматриваться – видишь практически реальную сцену! Команда должна уметь подготовить подробный прототип всего за несколько дней. Такой прототип должен свободно подключаться к тестовому инструментарию, службам виртуализации и другим элементам платформы, чтобы вы могли непосредственно наблюдать, как он взаимодействует с вашей системой. Прототипы нужны для того, чтобы их тестировать. Они – ваш последний рубеж обороны перед тем как придется тратить деньги на создание реального рабочего API.
Здесь этап сборки завершается. Далее мы должны сформулировать рабочий план, установить дедлайны и приступать к превращению прототипа в продукт. Набросок и прототип требовались нам, чтобы проработать детали, выявить баги, т.д. Сам по себе процесс сборки не так интересен. Просто нужно каждый день показывать готовый результат, шаг за шагом воплощать API, пока работа не будет готова. Многие компании стремятся к тому, чтобы на сборку API уходило не более 90 дней.
Три кита управления API
Наконец, если рассмотреть ситуацию шире, чем на уровне проектирования и реализации отдельно взятого API, в организации нужно придерживаться жизнеспособной программы работы с API и применять общие рекомендации по разработке API, которые будут известны всем командам. Внятная регламентация позволяет контролировать разработку API в масштабах всего предприятия, не вдаваясь при этом в излишний надзор над деталями реализации.
Эрик Уайлд, мой коллега из API Academy, подчеркивает, как важно «управлять ландшафтом ваших API», то есть, регламентировать три ключевых элемента программы API: протоколы, форматы, терминологию.
Регламентация протоколов – это четкие указания, какие протоколы уровня приложений должна поддерживать команда разработчиков API, готовя новые релизы. В большинстве компаний считается, что все новые API должны поддерживать HTTP. Некоторые также указывают и другие, необязательные протоколы, например, MQTT, Thrift и другие двоичные протоколы. Здесь наиболее важно заранее сообщить всем командам: «Если вы хотите гарантировать интероперабельность ваших API в будущем, то должны использовать эти протоколы». Для выполнения этого правила желательно использовать конвейер непрерывной доставки.
Регламентация форматов означает, что нужно условиться, в каких форматах данные будут пересылаться между сервисами. Практически все браузеры ожидают отклика в HTML-формате – точно так и на уровне вашего API нужно определиться, в каком формате он будет взаимодействовать со всей экосистемой. В большинстве компаний предпочитают простые форматы, например, JSON, XML или CSV, но в их моделях сообщений недостает ключевых метаданных, в частности, имен объектов, ссылок и форм ввода – а они необходимы для долгосрочных взаимодействий. С другой стороны, мне известны и такие компании, в которых используются более продвинутые форматы, например, HAL, Siren и Collection+JSON для API на базе HTTP. Для бинарных взаимодействий между сервисами многие организации берут за основу protobuf и подобные форматы. Независимо от того, какой формат вы выберете, важно проверить его в вашем сборочном конвейере, убедившись таким образом, что в продакшен поступают лишь API, полностью соответствующие регламентации.
Третий кит управления API – это терминология. В данном случае речь идет о контроле над названиями точек данных и идентификаторов действий, используемых при обмене сообщениями между сервисами. Придерживаясь терминологии, организация может не сомневаться, что новые сервисы будут нормально восприняты уже существующими. Вспоминая «общий язык», предложенный Эриком Эвансом для предметно-ориентированного проектирования (DDD), отмечу, что выбранная вами терминология нужна для того, чтобы рассуждать о наиболее критичных бизнес-операция. Должно быть непросто выпустить в продакшен такой сервис, в котором используются «совершенно новые» названия полей данных и идентификаторов действий. Напротив, элементы сборочного конвейера должны проходить проверку на соответствие общей терминологии, принятой во всей компании, а выбивающиеся из этой терминологии API не должны попадать в продакшен.
Усвоив эти принципы: «Первым делом — API», «эскиз-прототип-сборка» и «три кита управления API», ваша команда сможет использовать свои API на полную мощность, ничуть не рискуя их стабильностью во время выполнения.