Привет, Хабр! На связи Вячеслав Шмельцер, backend-разработчик, и Рамиль Алешкин (alewkinr), Product Owner Консоли управления #CloudMTS. На этой неделе мы выкатили beta-версию API нашей облачной платформы. Да, это гигиенический минимум для провайдера, без которого разработчикам (и не только) облако будет малоинтересно. Поэтому хвастаться не будем. Вместо этого расскажем, чем руководствовались и на что обращали внимание при разработке API, чтобы сделать его функциональным, масштабируемым и удобным для наших пользователей. Надеюсь, что наш подход окажется полезным тем, кому только предстоит написать API для своего сервиса.  В Консоли управления пользователи могут создавать и управлять различными сервисами, мониторить и биллить потребляемые ресурсы. Сейчас клиентам доступно 11+ облачных сервисов. Каждый из них разрабатывается и поддерживается отдельной командой центра разработки. У каждой команды свои методики и подходы, в том числе и к разработке API. Собственно, нашей первой задачей стало — сформировать единый подход к проектированию архитектуры API, ее дальнейшей поддержке и развитию.  Вторая задача — это обеспечить слабую связность между компонентами консоли при сохранении единого интерфейса API. Мы поставили перед собой цель — создать гибкое решение, которое могло бы адаптироваться к уже запущенным и новым сервисам. Третья — обеспечить эффективную коммуникацию между модулями API в условиях геораспределенной архитектуры платформы. Различные компоненты системы находятся в физически изолированных сетевых подсистемах, что приводит к увеличению задержек при нестабильности сети.  Чтобы решить эти задачи и задать основу единого фреймворка, мы обозначили общие принципы, требования и ограничения, на которые опирались в ходе проектирования и обсуждений с командами. Вот они: API может быть только асинхронным. Для создания виртуальной машины, кластера Kubernetes или базы данных PostgreSQL на облачной платформе необходимо выполнить множество операций, чаще всего параллельно. Мои коллеги подробно рассматривали процесс в этой статье. Создание экземпляра облачного сервиса может занимать от нескольких минут до получаса, поэтому ключевые методы нашего API могут быть только асинхронными.  При отправке запроса от пользователя запускается операция, которую можно отслеживать в консоли, чтобы узнать, успешно ли она выполнилась. Для нас также важно быстро дать знать пользователю о некорректно введенной информации или невозможности выполнить команду через UI. Для этого входящий запрос сначала проходит ряд проверок в синхронном режиме: если все условия разрешают выполнение команды, то сервер отвечает HTTP-статусом 202 и отправляет команду в очередь на выполнение. API минималистично и едино для всех продуктов платформы. Дизайн API — отдельный вид искусства, которому, к сожалению, не учат. Сложность состоит в том, чтобы создавать программный интерфейс, который будет интуитивно понятным, легким в использовании и функциональным. Единообразие в названиях методов и параметров, однотипная структура ошибок и минималистичность API упрощают понимание и использование. В результате пользователь тратит меньше времени на чтение документации, а команде разработки будет легче поддерживать решение. Но для этого нужно будет потратить больше времени на этапе проектирования API. Мы сформулировали ряд принципов, которые, на наш взгляд, упростят API и которые мы сможем контролировать на стороне платформы: API следует общепринятым подходам проектирования REST. Мы решили взять за основу REST, так как с помощью него можно достичь единообразия, масштабируемости, гибкости, производительности и простоты использования API. Вот правила, которых мы придерживались: Однако некоторыми подходами пришлось пренебречь из-за специфики облачного провайдера. Например, мы изменили подход формирования URI-доступа к ресурсам. Так, в классическом REST-подходе рекомендуется отображать иерархию в пути запроса. Например, запрос на добавление новой книги для конкретного автора может выглядеть так: POST /v1/authors/:12345/books — books (книги) лежат на уровень ниже, чем авторы. Для облачного провайдера такая упрощенная модель организации иерархии не подходит, так как многие ресурсы взаимосвязаны. Если оформлять URI способом, принятым в практике REST, API получится громоздким. В нашем примере любой запрос на создание выглядит так: POST /v1/services При этом связи между ресурсами мы переместили в тело запроса, например Рассмотрим более реалистичный пример подробнее.  Пользователь хочет создать сеть (network), подсеть (subnet) и зарезервировать IPv4 внутри подсети.  Для этого ему нужно отправить несколько запросов: Запрос POST /v1/services создает сеть.
Запрос POST /v1/services/:networkId/subnet создает подсеть.
Запрос POST /v1/services/:networkId/subnet/:subnetId/ipv4 резервирует IPv4 в конкретной подсети. На бумаге это выглядит логично и удобно, однако в реализации есть ряд подводных камней: Наш же подход уменьшает количество поддерживаемых API-методов, помогает организовать иерархичность любой глубины и позволяет внедрить множество разных типов связей, а не только иерархические. Далее рассмотрим общие механики API применительно к нашей задаче. Разработка публично доступного API накладывает требования на функциональность и работоспособность системы аутентификации и авторизации. Наш модуль Identity and Access Management (IAM) удовлетворяет этим требованиям, поэтому дополнительной работы, связанной с механикой входа, делать не пришлось, но кратко рассказать о подводных камнях, я думаю, будет полезно.  Можно выделить два ключевых требования: Мы решили использовать стандартные stateless JWT. В случае с аутентификацией по логину и паролю пользователя они выписываются на фиксированное время (10–20 минут). В случае сервисной учетной записи пользователь через консоль управления самостоятельно задает дату, когда токен перестанет быть активным. Авторизация запросов выполняется на уровне общего API-шлюза, который получает токен из заголовка Authorization. Эта практика кажется самой простой и распространенной на текущий день. Для ошибки аутентификации мы используем код ответа 401 Unauthorized, а если у пользователя не хватает привилегий для доступа к указанному ресурсу, сервер вернет 403 Forbidden. Текущая модель авторизации на 100% закрывает наши потребности в рамках разработки API. Контроль доступа играет важную роль в обеспечении безопасности системы. Но на первых этапах разработки этому часто не уделяют должного внимания, надеясь на то, что защиту можно обеспечить на уровне UI. При разработке публичного API механику нужно внедрять повсеместно. В нашем IAM реализована модель управления доступом на основе ролей (Role-Based Access Control, RBAC). Есть несколько ключевых ролей, которые регламентируют разные уровни доступа: администратор, редактор, наблюдатель. Все привилегии пользователям выдаются на уровне ключевой сущности в нашей платформе — проекта. Таким образом, администратор проекта имеет полные права на управление всеми услугами внутри проекта, а наблюдатель может только просматривать по всем сущностям, внутри проекта. С технической стороны наш модуль контроля доступа — собственная разработка. Мы постараемся раскрыть детали реализации в других статьях. В настоящее время ролевая модель может быть не очень гибкой, однако мы планируем ее расширять, внедряя новые модели управления доступом, например ABAC. Подробности о планах по развитию API будут описаны в конце статьи. Для справедливого доступа к API и для защиты от злоумышленников, следует продумать механизм ограничений и квот. Мы рассматривали несколько механизмов: Leaky Bucket. Задача алгоритма — ограничить полосу пропускания канала и в то же время гарантировать некоторую скорость передачи данных. Token bucket. Задача алгоритма — разделить запросы и ограничения, выставляемые платформой. Это делается за счет токенов, которые начисляются «на баланс» пользователя API. Работая с API, пользователь расходует токены, а следовательно, и свою квоту. Fixed Window. Задача алгоритма — ограничить количество запросов в рамках временного интервала. Это помогает избегать непредвиденных всплесков в нагрузке на сервер. Sliding Log. Алгоритм очень схож с Fixed Window, но тут появляется возможность установки индивидуальных ограничений по каждому пользователю. Sliding Window. Гибридный подход, который сочетает в себе механики Fixed Window и Sliding Log. Алгоритм позволяет установить ограничения на каждого пользователя в единицу времени.  Для решения нашей задачи подошел бы любой из вышеописанных алгоритмов, поэтому ключевым фактором принятия решения была стоимость внедрения и поддержки. На этапе бета-версии мы выбрали наиболее простой и быстрый для внедрения подход — Sliding Window. Он гибкий и дает возможность плавно ограничивать скорость запросов в заданном временном окне. Также реализация этого алгоритма есть в gochi, который используется в нашей команде. Чтобы покрыть все нюансы работы API, мы опираемся на стандартные коды HTTP-статусов, но расширяем их с помощью специфических кодов в теле ответа сервера. Вот некоторые примеры этих кодов: Вот пример структуры, когда запрошенный ресурс не найден: В примере возвращается HTTP-статус 404 с кодом внутри тела ResourceNotFound. Это поможет отличить друг от друга два кейса с одним кодом 404: несуществующий URL и данного ресурса нет в платформе. Этот подход мы позаимствовали из API-гайда Google. В нашем облаке много модулей, каждый из которых развивается отдельной командой. Но платформа должна агрегировать и типизировать ошибки этих модулей, поэтому взаимодействие между различными командами осуществляется по одному контракту ошибок. Нет общепринятых стандартов или принципов внедрения пагинации, фильтрации и сортировки в API, поэтому каждая команда разработчиков формирует свой взгляд. Мы вдохновлялись подходом Google, который они используют при разработке своего API. Параметры пагинации и сортировки, которые мы передаем как query-параметры в GET-запросах, выглядят так: Также передаются query-параметры фильтрации. Например, поиск сервисов по определенным id можно передать, используя следующие query-параметры:  ?filter.serviceId=“123”&filter.serviceId=“456” В ответе для запросов, где возможна пагинация, в JSON обязательно присутствует вложенный объект pagination, например: Для обеспечения совместимости при изменении API мы используем мажорные (в терминах semver) версии в URL-адресах API-методов. Если вносятся изменения, которые не могут быть обратно совместимыми, мы добавляем новую версию эндпоинта. Однако важно не только добавлять новую функциональность в API, но и выводить из эксплуатации устаревшие механики, поддержка которых приводит к дополнительным расходам в разработке. При разработке подхода к деприкации мы руководствовались двумя RFC: один и два. Мы объединили оба решения и немного доработали для соблюдения правила минимализма.  В нашем случае, если API-метод выводится из эксплуатации, сервер добавит заголовок SUNSET, который может выглядеть следующим образом: SUNSET: 2023-10-10T23:59:44+00:00; /v2/products; http://docs.cloud.mts.ru/api/public-hub.html Таким образом, мы гарантируем совместимость при изменении API через версионирование эндпоинтов. При деприкации версии API сообщаем пользователям о сроке прекращения поддержки, рекомендуемых заменительных методах и соответствующей документации для миграции. В качестве инструмента для документирования нашего REST API мы выбрали Swagger и практически сразу автоматизировали генерацию спецификации из аннотаций в коде с помощью популярного на GitHub решения. Сначала это казалось очень удобным, поскольку код и документация не отставали друг от друга, а мы экономили ресурсы команды. Спустя несколько спринтов мы отказались от автогенерации по следующим причинам: После обсуждений было принято решение о том, что OpenAPI 3.0 будем писать вручную. Да, это означало, что код будет не совпадать с документацией и что мы будем тратить больше времени на написание и поддержку инструкций. Зато этот вариант даст нам больше гибкости и контроля в том, какую документацию получит пользователь. Чтобы гарантировать корректность спецификации и минимизировать человеческий фактор, мы решили внедрить линтер для OpenAPI 3.0 документации и встроить его в CI/CD-процесс доставки на боевое окружение. Вот что должен был уметь наш линтер мечты: Подходящий линтер искали здесь. Всем нашим требованиям удовлетворил vacuum. Это довольно быстрый линтер, который выявил много важных замечаний и помог упростить ревью нашей спецификации. Часто встречаюсь с заблуждением, что тестирование — наиболее простой этап разработки, но по нашему опыту это не так. Более того, это не бесплатно для продуктовой команды, поэтому на первых этапах разработки API стоит критически относиться к функциональности, которую вы планируете покрыть автотестами. Для нашей бета-версии API мы определили следующие стейтменты: Мы запускаем регрессионные тесты, которые проверяют эти аспекты при каждом релизе. Для тестирования используем pytest и общий фреймворк тестирования всех команд разработки в #CloudMTS. Присматривались к тестированию API через Postman, но решили пойти путем, который уже отработан на других модулях. Будет интересно, если поделитесь своим опытом в комментариях. Графики и прочая визуализация взаимодействия пользователей с нашим программным интерфейсом помогает заметить проблемы до того, как это повлияет на пользовательский опыт. А еще это отличный способ корректировать роадмап разработки, опираясь на востребованные пользователями API-эндпоинты. Мы придерживаемся итеративного подхода, поэтому на запуске beta-версии решили, что нам будет достаточно стандартных RED-метрик. При необходимости эту модель можно расширять дополнительными метриками или лейблами (для сегментации базы пользователей/запросов). Это система метрик, используемая для измерения производительности и надежности работы системы, особенно в контексте распределенных систем обработки данных. Она состоит из следующих компонентов: Rate измеряет скорость поступления событий или сообщений в систему. Обычно измеряется в количестве событий или сообщений, полученных за определенный промежуток времени. Скорость важна для понимания нагрузки, с которой система справляется, и может помочь определить, является ли она устойчивой или находится на грани перегрузки. Errors отслеживает количество ошибок или отказов в обработке событий. Ошибки могут быть связаны с различными аспектами системы, включая потерю сообщений, превышение времени обработки или другие виды сбоев. Измерение ошибок позволяет идентифицировать проблемы в системе и принять меры для их устранения. Важно отметить, что ошибки бывают в любой более-менее сложной системе (сетевые сбои, баги, человеческий фактор, легаси в данных). Мы следим, чтобы их количество не превышало средние значения в 90, 95 и 99 перцентилей. Duration отражает время, затраченное на обработку каждого события или сообщения в системе. Измерение продолжительности позволяет оценить производительность системы и определить, насколько быстро она обрабатывает поступающие запросы. Более длительная продолжительность может указывать на проблемы с производительностью или неэффективное использование ресурсов. Для построения графиков мы используем Grafana. Все дашборды наших сервисов шаблонизированы с помощью grafonnet. Они хранятся в виде кода в репозитории сервиса и доставляются в Grafana в рамках CI/CD с помощью grizzly. Пример организации дашбордов можно посмотреть тут.  Мы также активно используем Sentry для мониторинга и более удобной работы с исключениями (exceptions), которые возникают на сервере или на клиенте. Sentry дает удобный инструментарий для отслеживания и трассировки ошибки внутри приложения и может быть полезна, если у вас сложная, многослойная архитектура приложений. Для уведомлений о проблемах используется alertmanager, так как на уровне инфраструктуры используется prometheus-совместимый набор технологий. Мы не выделяем публичный API в какой-то отдельный продукт или модуль, но понимаем, что это новый пользовательский интерфейс (как и web-интерфейс). Он может вызывать вопросы, с которыми не сталкивалась наша поддержка ранее. В нашем облаке мы организовали отдельный уровень поддержки (developer level support, DLS) — это технические специалисты, которые занимаются сложными пользовательскими кейсами. Чтобы они лучше понимали, какие изменения происходят в продукте, мы нередко интегрируем их в наши scrum-ритуалы, проводим воркшопы и пишем внутреннюю документацию, которая разъясняет технические аспекты реализации различных модулей, в том числе и публичного API. В результате такой организации работы мы получили два основных плюса: Продуктовые команды часто пренебрегают этими инструментами, поскольку считают, что спецификация openAPI в полной мере описывает контракт взаимодействия. На старте мы сталкивались с похожей проблемой при разработке внутренней версии API, однако быстро осознали, что релизноутсы нужно писать подробно и понятно, погружаясь в конкретные юзкейсы пользователей. У нас пока нет готового решения по автоматизации этого процесса. Надеюсь, что популяризация LLM поможет упростить эту задачу и генерировать контент, который нужно будет только вычитать редактору. Мы постарались сделать гибкий инструмент, который поможет пользователям автоматизировать управление их облачной инфраструктурой. В этой версии мы не успели реализовать широкий спектр функций, но заложили в основу все, чтобы быстро развивать и гибко подстраивать API под новые бизнес-требования. В ближайшее время будем работать над следующими направлениями:  Сейчас мы запускаем бета-версию API и будем постепенно добавлять новые паттерны использования, исправлять неточности и баги (куда без них). Будем рады, если протестируете нашу бета-версию API для сервисов Cloud Compute (виртуальные машины) и Managed Service for Kafka и поделитесь обратной связью. Тем более что для всех новых пользователей доступен приветственный грант в 5 000 рублей.