Интеграция систем в сложном IT-ландшафте всегда вызывает боль, и мы уменьшаем нашу боль посредством абстрактного слоя - Enterprise API. Enterprise API – это набор API, которые покрывают основные бизнес-домены и являются decoupling слоем между системами.  Мне печально это утверждать, но, к сожалению, наш IT-ландшафт (IT-landscape) сложен. Очень сложен. Очень. IT-ландшафт Deutsche Telekom, как и многих других традиционных телекоммуникационных компаний – рос десятилетиями. Рост обуславливался, с одной стороны, неоднократным появлением новых коммуникационных технологий на протяжении этих лет (ISDN, ASDL, VDSL, GPON, 3g/LTE, SDN etc), а также слиянием и поглощениями в различных направлениях бизнеса.  Таким образом, со временем, ландшафт накопил большой технический долг. Причем, долг не только в старых IT системах, которые сложно развивать и поддерживать, например, на устаревающих технологичных стеках, но в интеграционном подходе в целом. Сложность ландшафта, приводит к тому, что изменения в IT становятся все более рискованными и требуют все более масштабных тестов, отнимающих все больше и больше времени и денег. Мы уже не раз запускали проекты по упрощению и трансформации ландшафта, какие-то были более успешные были какие-то не очень. Например, между частями ландшафта OSS (Operations Support Systems) и BSS (Business Support System) количество связей не так много: то есть нам удается отдельно управлять системами, связанными с клиентами (BSS) и системами, ориентированными на управления сетью и ресурсами (OSS). Несколько лет назад пришло понимание, что построение общего/единого слоя API позволит нам еще более гранулярно разделить ландшафт и сделать его более управляемым и гибким. И мы пришли к идее Enterprise API. Enterprise API, в нашем понимании, это набор API, который закрывает собой наши бизнес-возможности (business capabilities) и позволяет использовать их в остальном ландшафте. Пример списка business capabilities для телеком области, можно посмотреть в документе GB1007A от TMF Forum (https://www.tmforum.org/resources/standard/gb1007a-business-architecture-capability-reference-map-v4-0-0/). Product Management - The ability to conceptualize, design, develop, bundle, price, launch, maintain and retire goods and services offered by the Business. Customer Management - The ability to control, predict, process, organize, present and analyze all information, documents, preferences, experiences and history related to an individual or organization that has, plans to have or has had an account with the organization. Incident Risk Management - The ability to identify, assess, aggregate, articulate, and incorporate various exposures to harm, danger, or loss associated with a given incident. Network Management - The ability to design the architecture and plan, develop, deploy, monitor and report on the communications network infrastructure. Order Management - The ability to place, validate, cancel, change, track, fulfill and otherwise manage a request by one party to another to buy, sell, or exchange goods or services. И наша цель: построить набор API, позволяющий использовать функциональность этих IT-доменов для построения новых бизнес процессов. Во-первых, конечно, уменьшает связанность систем.  И API слой позволяет разделить наш IT-ландшафт на независимые поддоменны (domains/subdomains). В частности, разделить системы бекоффиса (backends/back-office) и системы которые тесно взаимодействуют с клиентами (т.н. touchpoint). К "тачпоинт"  у нас относятся такие приложения как: порталы, системы самообслуживания,      системы поддержки и т.п. С помощью единого слоя Enterprise API мы гармонизируем формат данных и бизнес-объекты, которые используются в нашей предметной области. API скрывает часть "кухни", которая творится на стороне back-office систем.      (например, там могут быть несколько IT-систем, которые как-то распределяют      между собой управление данными / процессами, и потребитель не должен      думать и знать об этой сложности). Ну и естественно, сокрытие бэкенд слоя позволяет нам более безопасно проводить рефакторинг нашего IT-ландшафта. Например, незаметно выводить из эксплуатации устаревшие системы (Legacy). Enterprise API в нашем ландшафте базируется на наборе спецификаций, который подготовлен проектом Tele Management Forum Open API. TMF Open API это набор готовых спецификаций, которые могут быть использоваться как есть или расширяться под потребности конкретного телеком оператора. TM Forum - это объединение операторов связи и вендоров, которое вырабатывает рекомендации для IT систем в телеком области. (https://www.tmforum.org/) В данном случае, нас сегодня будет интересовать проект TMF Open API. (https://www.tmforum.org/open-apis/). Прошу, не путать его с OpenAPI Specification v3 (https://swagger.io/specification/).  TMF Open API - это набор готовых спецификаций (пока в формате swagger 2), сопровождающая документация и сертификационный набор, которые позволяет проверить насколько ваша реализация API все еще удовлетворяем критериям TMF Open API.   Список готовых API доступен по ссылке: https://projects.tmforum.org/wiki/display/API/Open+API+Table. Дата модели, которые используется в TMF Open API, базируются на давно известном для телеком-компаний Information Framework (aka SID - https://www.tmforum.org/information-framework-sid/). Эти модели разбиты по доменам, хорошо продуманы и проверены годами. И, что самое главное, они действительно удобны для представления данных и передачи их между системами. С нашей точки зрения, эффективной конструкцией для реализации Enterprise API является вот такой треугольник. Команды разработки, как провайдеров (providers), так и консюмеров (consumers) тесно взаимодействуют с API Portfolio Management и архитектурной командами. Таким образом, команды реализуют интерфейсы в существующих бэкенд системах, или пишут адаптеры, где это целесообразно, интегрируют существующие тачпоинт-системы с Enterprise API или создают новые приложения, которые уже используют Enterprise API в качестве шлюза к данным бэкенд систем. В процессе разработки сервисов, команды разработки предлагают изменения в спецификации API и эти изменения в виде Push-Request/Merge-Request попадают в команду API Portfolio Management (API PM). Команда API PM, в свою очередь, обсуждает с командами разработки и архитектурной командой изменения в API, и меняет спецификации API. Кроме этого, API PM занимается описанием основных сценариев использования API (UseCases). Также API PM ответственна за создание и развитие руководств и практик (guidelines and best practice), которые касаются разработки API и совместно с командой разработки отвечают за качество API. Архитектурная команда, в свою очередь, обеспечивает общий архитектурный надзор (agile architecture governance), работает совместно с представителями бизнеса (business stakeholders) над приоритетами задач и направлением развития Enterprise API. В нашей организации мы поддерживаем два документа, которые касаются разработки API: Enterprise API Guideline - зафиксированы требования, которые обязательны для тех API, которые становятся доступными для всей организации (на всем ландшафте).  API Standards & Conventions - относится не только к Enterprise API, но и выступает рекомендацией при создании внутренних системных или локальных REST API. Оба документа организованны как набор markdown файлов в gitlab repository, и, в общем, любой сотрудник может сделать запрос на изменение (merge request). И этот запрос будет принят или как минимум будет обсужден.  Чаще всего, коллеги просто создают JIRA тикет с описанием ожидаемых изменений и уже потом совместно решаем, как лучше его задокументировать желаемые изменения. В целом, поддержка документации, довольно демократичный процесс и основан на тесном взаимодействии вовлеченных сторон. Публикуются оба документа как часть Developer портала, но о нём чуть позже. Enterprise API Guideline cодержит: Definition of Done (DoD), который описывает, что необходимо сделать, чтобы API вошел в линейку Enterprise API.  Набор паттернов специфичных для реализации Enterprise API.  Описание общих дата моделей, которые единые для всего набора Enterprise API.  Также тут задокументировано соответствие (mapping) API и бизнес-возможностей (business capabilities) IT-ландшафта. API Standards & Conventions, в свою очередь, описывает: Содержит в себе набор выбранных практик, которые мы используем в создании наших API.  Как вы знаете, при построении REST API слишком много опций, как можно реализовывать или описывать ту или иную задачу. А т. к. мы хотим получить более-менее однородный набор API в нашем Enterprise API, то из всех опций мы выбираем одну и на нее просим ориентироваться. Для примера: четко описали формат сообщений об ошибках. зафиксировали ограниченный набор кодов ответов HTTP, которые мы используем в наших API. набор HTTP заголовков мы так же перечислили и указали сценарии их применения. Также в гайдлайне мы описали наши договорённости по наименованию. Расписали основные используемые паттерны. Например: наш подход к реализации постраничного вывода (pagination), версионирование API. API спецификации и сопутствующая документация хранятся у нас в gitlab и при любом изменении спецификации стартует CI/CD pipeline, который автоматизирует задачи по валидации, подготовки отчетов и публикации API. В начале pipeline находится очень простой шаг. Checkversion проверяет, что версия API спецификации изменилась в большую сторону, по сравнению с уже опубликованными API спецификациями. Хотя бы минорная (minor) часть версии должна увеличиться. Далее проверяется наличие Changelog документа.  У нас changelog это yaml файл, который заполняется вручную, но осознанно в machine-readable формате для обработки и анализа. Этот файл содержит список изменений для каждой версии API. А так как у нас решено, что для каждой мажорной (major) версии спецификации API у нас отдельная ветка в git, то на этом же шаге проверяем и соответствие ветки git с версий спецификации. Шаг реализован как shell скрипт. Следующие два шага подготавливают документацию для дальнейшей публикации. Первый шаг генерирует документацию. Он обрабатывает все markdown файлы, которые идут вместо со спецификацией и формирует веб страницы, docx и pdf документы. Этот шаг у нас уже не актуален, т. к. сейчас эту работу выполняет "портал разработчиков" (developer portal), поэтому сейчас на этом шаге мы только формируем веб страницу для changelog основываясь на yaml файле, который описан выше. В этом шаге используется, pandocs, mkdocs (в котором кроме прочего есть плагин для plantuml) Второй шаг, подготовки спецификации (prepare-spec), имеет свою имеет свою предысторию. Для обеспечения консистентности дата моделей используемых в API мы решили использовать ссылки между схемами в API спецификациях. И теперь часть спецификаций вместо того, чтобы самим определять схему данных, ссылаются на "мастер"-спецификацию, которая содержит описание схемы данных. Например, для ресурса Account "мастер" спецификацией будет Account Management API, а все другие спецификации, которым нужен это объект, должны просто ссылаться на его описание в Account Management API. Ссылка на схему, в нашем случае, выглядит так: https://artifactoryhostname/eapi/tmf666_account_management/5.3.1/specification.yaml/# /definitions/Account В итоге мы получаем спецификацию, которая вместо части своих схем содержит ссылки, с такой спецификацией работает большинство инструментов разработки, вы можете генерировать код, просматривать и редактировать спецификацию. Но это не всегда удобно, т. к.  необходим доступ к "мастер"-спецификациям. Поэтому на это шаге в pipeline заменяем все такие ссылки копией схемы данных из "мастер"-спецификации. У нас это делается с помощью собственного java-инструмента, но точно помню, что python библиотека Prance может делать это из коробки буквально в одну строку кода. Это первый из трех шагов, которые ответственны за различного рода проверки API спецификаций и их задача гарантировать стабильное и предсказуемое качество спецификаций. В одной из глав гайдлайна "API Standards & Conventions" мы привели довольно большое количество примеров изменений спецификаций, которые приводят к несовместимости между версиями API и требуют создания новой major версии API. Первые 5 таких примеров приведены на иллюстрации: В pipeline на шаге breaking-changes как раз и сравнивается предыдущая и новая версия спецификации и анализируется, являются ли найденные изменения совместимыми или несовместимыми. Естественно, эта проверка не панацея, и список наших примеров не исчерпывающий. Тем более, проверяется только синтаксическая часть спецификации, а не семантическая. Так что часть существенных изменений могут все равно быть пропущены. Но этот шаг нам все равно полезен для дополнительной проверки и защиты от случайных ошибок. В отчете видно, что были добавлены: новый код ответа (400), добавлены дата схемы (PriceAlteration, Money etc) и это допустимые изменения, а вот удаление заголовка X-Total-Count из ответа - является несовместимым изменением и для такого изменения должна быть создана отдельная major версия спецификации. Реализован шаг как самодельный java-инструмент. Очень простой шаг в pipeline, и, к сожалению, у нас он работает только для спецификаций в формате swagger 2.0.  Шаг формирует детальный отчет обо всех изменениях в спецификации. Этот отчет может быть использован как автором спецификации, чтобы проверить, что действительно нет случайных изменений и все, что в отчете, было ожидаемо. Также этот отчет полезен и тем, кто реализует сервис по этой спецификации и, естественно, потребителям сервиса, т. к. позволяет быстро понять изменения. Шаг реализован на базе проекта swagger-diff (https://github.com/Sayi/swagger-diff)  Наверное, это самый интересный шаг нашего pipeline. Как вы помните, в гайдлайне у нас есть набор правил, соглашений и рекомендаций о том как должна выглядеть спецификация API. Эти правила включают в себя: кодов ответов HTTP, которые мы используем в наших API набор HTTP заголовков (headers) наши договорённости по наименованию атрибутов, схем и точек вызовов (endpoints). наличие и корректное заполнение информационных полей (title, name, descriptions, version etc) Media types для запросов и ответов. ( application/json-patch+json, application/json       etc) etc Пару примеров таких правил ниже: operation-operationId-format:  Operation `operationId` MUST be defined in lowerCamelCase.  oas3-valid-schema-example: Examples must be valid against their defined schema. oas3-server-trailing-slash: Server URL should not have a trailing slash. response-object: Operation response MUST not response an array, but an object. Как раз на шаге spectral используются эти правила и проверяются API спецификации на соответствие им. Инструмент использует правила в виде конфигурации, где в декларативном виде прописаны условия проверки. Правило: request-mediatype-oas3:  Operation request MUST only use allowed HTTP media types. Please refer to HTTP Media Types chapter.  И его представление в виде yaml конфигурации: Базовый набор правил валидации можно посмотреть и загрузить с сайта spotlight.io (https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md). Правила специфичные для нас мы добавили самостоятельно. Но даже использование только базовых правил уменьшит количество ошибок в написании спецификации и сделает API спецификации более единообразными. Этот шаг реализован с помощью инструмента Spectral (https://stoplight.io/open-source/spectral).  Самый простой шаг: после того, как мы проверили новую спецификацию, в git ставится метка с текущей минорной версией API, чтобы потом всегда можно было пересобрать артифакты. Мы используем artifactory как общее хранение для всех спецификаций. То есть как некий single point of truth. Публикуются следующие артифакты :  API спецификация, причем как в оригинальной форме так и уже с отрезолвенными ссылками на дата модели (см. шаг prepare-spec) В json и yaml, вне зависимости от того в каком формате была разработана спецификация. Changelog: markdown и исходный yaml файл. Отчет об отличиях в спецификации по сравнению с предыдущей версией. И, конечно, документация. (как я отметил выше, публикация документации это уже deprecated шаг, т. к. сейчас этим занимается developer portal) Формально это уже не часть CI/CD pipeline, но "портал разработчиков" важная часть нашей API экосистемы. После публикации спецификации в artifactory срабатывает триггер, который обновляет информацию на "портале разработчиков". Портал публикует спецификации, документацию, которая поясняет, как используется API. Также на портале публикуются ранее упомянутые гайдлайны и различные HowTo, которые помогают разработчикам взаимодействовать с Enterprise API. Построение единого слоя Enterprise API упрощает работу со сложным IT ландшафтом (декаплинг бизнес-доменов, контроль развития ландшафта, стоимость интеграции новых систем)  Организации Enterprise API практики требует не только организации архитектурного надзора, но и изменений в структуре компании. БОльшую часть проверок качества API необходимо реализовывать как автоматические тесты и желательно сделать их частью CI/CD pipeline. Статья выше описывает как мы стоили Enterprise API в рамках IT ландшафтаTelekom Deutschland GmbH, но кроме немецкого рынка концерн Deutsche Telekom AG контролирует/владеет интернет-провайдерами в ряде европейских стран. Magenta Telekom (Austria) T-Mobile Netherlands T-Mobile Polska T-Mobile Czech Republic Slovak Telekom Magyar Telekom Makedonski Telekom Novatel Hrvatski Telekom Сrnogorski Telekom OTE Telekom Albania Telekom Romania Для того, чтобы наши клиенты могли пользоваться едиными порталами и приложениями самообслуживания (touchpoint) вне зависимости от того ,какой конкретно европейский провайдер предоставляет ему услуги, мы унифицируем способ взаимодействия между touchpoint и IT ландшафтами операторов, находящихся в разных странах.  Один из элементов программы такой унификации - построение слоя Magenta API (да, да, мы очень любим маджентовый цвет #E10075) который является единым API и скрывает за собой что пользователи, их сервисы и продукты обрабатываются разными IT-ландшафтами, принадлежащими по сути разным компаниям.  https://www.youtube.com/watch?v=NSAxKx1ykFM - Видео с доклада на ArchDays'21 "Pipeline for Enterprise API", по этому докладу и написана статья, но в видео докладе больше примеров и может что-то более детально объяснено.  https://habr.com/ru/company/deutschetelekomitsolutions/blog/570850/ - Статья на Хабре о построении Enterprise API для Deutsche Telekom, написана коллегами (системные архитекторы, PO, PM и разработчиками). Статья раскрывает другие аспекты этого проекта, в том числе: SAFe фреймворк, технологический стек, T-shape специалисты. https://projects.tmforum.org/wiki/display/API/Open+API+Table - Таблица TMF OpenAPIs. https://swagger.io/docs/specification/using-ref/ - Использование ссылок (references) в Open API Specification. https://github.com/Sayi/swagger-diff - Swagger Diff, open source инструмент для построения отчета о разнице в API спецификациях. https://stoplight.io/open-source/spectral/ - Spectral, Open Source JSON/YAML Linter. Инструмент валидации спецификации по правилам.  https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md - Правила для Spectral. Lead Architect