Pipeline for Enterprise API

Интеграция систем в сложном IT-ландшафте всегда вызывает боль, и мы уменьшаем нашу боль посредством абстрактного слоя - Enterprise API.

Enterprise API – это набор API, которые покрывают основные бизнес-домены и являются decoupling слоем между системами.

Зачем нам нужен Enterprise API?

Мне печально это утверждать, но, к сожалению, наш 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/).

И наша цель: построить набор API, позволяющий использовать функциональность этих IT-доменов для построения новых бизнес процессов.

Что же дает нам выделение Enterprise API слоя?

Во-первых, конечно, уменьшает связанность систем.  И 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 это набор готовых спецификаций, которые могут быть использоваться как есть или расширяться под потребности конкретного телеком оператора.

Организационная структура.

С нашей точки зрения, эффективной конструкцией для реализации 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.

Гайдлайны (Guidelines)

В нашей организации мы поддерживаем два документа, которые касаются разработки API:

• Enterprise API Guideline - зафиксированы требования, которые обязательны для тех API, которые становятся доступными для всей организации (на всем ландшафте).

• API Standards & Conventions - относится не только к Enterprise API, но и выступает рекомендацией при создании внутренних системных или локальных REST API.

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.

CI/CD Pipeline

API спецификации и сопутствующая документация хранятся у нас в gitlab и при любом изменении спецификации стартует CI/CD pipeline, который автоматизирует задачи по валидации, подготовки отчетов и публикации API.

checkversion

В начале pipeline находится очень простой шаг. Checkversion проверяет, что версия API спецификации изменилась в большую сторону, по сравнению с уже опубликованными API спецификациями. Хотя бы минорная (minor) часть версии должна увеличиться.

Далее проверяется наличие Changelog документа. 

У нас changelog это yaml файл, который заполняется вручную, но осознанно в machine-readable формате для обработки и анализа. Этот файл содержит список изменений для каждой версии API. А так как у нас решено, что для каждой мажорной (major) версии спецификации API у нас отдельная ветка в git, то на этом же шаге проверяем и соответствие ветки git с версий спецификации.

Пример chagelog.yaml

Шаг реализован как shell скрипт.

generate-doc & prepare-spec

Следующие два шага подготавливают документацию для дальнейшей публикации.

Первый шаг генерирует документацию. Он обрабатывает все 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 может делать это из коробки буквально в одну строку кода.

breaking-changes

Это первый из трех шагов, которые ответственны за различного рода проверки API спецификаций и их задача гарантировать стабильное и предсказуемое качество спецификаций.

В одной из глав гайдлайна "API Standards & Conventions" мы привели довольно большое количество примеров изменений спецификаций, которые приводят к несовместимости между версиями API и требуют создания новой major версии API.

Первые 5 таких примеров приведены на иллюстрации:

В pipeline на шаге breaking-changes как раз и сравнивается предыдущая и новая версия спецификации и анализируется, являются ли найденные изменения совместимыми или несовместимыми.

Естественно, эта проверка не панацея, и список наших примеров не исчерпывающий. Тем более, проверяется только синтаксическая часть спецификации, а не семантическая. Так что часть существенных изменений могут все равно быть пропущены. Но этот шаг нам все равно полезен для дополнительной проверки и защиты от случайных ошибок.

[main] INFO SpecificationCheck - Specification origin/tmf637-product-inventory.openapi.yaml version is V2
[main] INFO SpecificationCheck - Specification preparedFiles/tmf637-product-inventory.openapi.yaml version is V2
[main] INFO Swagger20Parser - reading from origin/tmf637-product-inventory.openapi.yaml
[main] INFO Swagger20Parser - reading from preparedFiles/tmf637-product-inventory.openapi.yaml
[main] INFO ResponseDiff - paths./Product/{id}.DELETE.responses response added: [400]
[main] WARNING ResponseDiff - paths./Product/{id}.GET.responses response headers removed: X-Total-Count
[main] INFO ModelDiff - Ref Model added: [PriceAlteration, RealizingResourceCriteria]
[main] INFO ModelDiff - Ref Model added: [Money, TimePeriod]
[main] ERROR App - Breaking changes found

Реализован шаг как самодельный java-инструмент.

diff-report

Очень простой шаг в pipeline, и, к сожалению, у нас он работает только для спецификаций в формате swagger 2.0. 

Шаг формирует детальный отчет обо всех изменениях в спецификации. Этот отчет может быть использован как автором спецификации, чтобы проверить, что действительно нет случайных изменений и все, что в отчете, было ожидаемо. Также этот отчет полезен и тем, кто реализует сервис по этой спецификации и, естественно, потребителям сервиса, т. к. позволяет быстро понять изменения.

Пример отчета ниже

Шаг реализован на базе проекта swagger-diff (https://github.com/Sayi/swagger-diff) 

spectral

Наверное, это самый интересный шаг нашего 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:
    description: Operation request MUST only use allowed HTTP media types.
    severity: error
    formats:
      - oas3
    given: $.paths.*.*.*.content
    then:
      field: '@key'
      function: enumeration
      functionOptions:
        values:
          - application/json
          - application/merge-patch+json
          - application/json-patch+json
          - application/problem+json

Базовый набор правил валидации можно посмотреть и загрузить с сайта spotlight.io (https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md). Правила специфичные для нас мы добавили самостоятельно.

Но даже использование только базовых правил уменьшит количество ошибок в написании спецификации и сделает API спецификации более единообразными.

Этот шаг реализован с помощью инструмента Spectral (https://stoplight.io/open-source/spectral).

tag

Самый простой шаг: после того, как мы проверили новую спецификацию, в git ставится метка с текущей минорной версией API, чтобы потом всегда можно было пересобрать артифакты.

publish-to-artifactory

Мы используем artifactory как общее хранение для всех спецификаций. То есть как некий single point of truth.

Публикуются следующие артифакты : 

• API спецификация, причем как в оригинальной форме так и уже с отрезолвенными ссылками на дата модели (см. шаг prepare-spec)

• В json и yaml, вне зависимости от того в каком формате была разработана спецификация.

• Changelog: markdown и исходный yaml файл.

• Отчет об отличиях в спецификации по сравнению с предыдущей версией.

• И, конечно, документация. (как я отметил выше, публикация документации это уже deprecated шаг, т. к. сейчас этим занимается developer portal)

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 контролирует/владеет интернет-провайдерами в ряде европейских стран.

Для того, чтобы наши клиенты могли пользоваться едиными порталами и приложениями самообслуживания (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.