Post #578

Или вот ещё в октябре OpenAPI Initiative выпустила первую версию спецификации Overlay : стандарта для описания изменений в спецификации API. Помните пост про метод PATCH и специальный тип документа для описания изменений ресурса? Вот такая же штука для изменения спецификации в формате OpenAPI. В Overlay предусмотрено пока два вида операций (actions): update и remove. Первая позволяет что-то добавить или изменить в исходной спецификации, вторая, соответственно, удалить. Что именно удалить или добавить — задается полем target, в который пишется путь в формате JSONPath. Вот, скажем, пример удаления из спеки всех упоминаний localhost: actions: - target: $.servers[?(@.url == 'http://localhost:8080')] remove: true Для чего могут понадобиться эти оверлеи? Например, как в примере выше — для удаления или замены адресов для API в разных контурах — базовая спека одна и та же, а для каждого контура свои адреса, и, например, свои требования к аутентификации. Или (не очень для нас актуальный пример) — описание API на нескольких языках. А вот это можно себе представить: автоматическая генерация OpenAPI спеки из кода без комментариев и описаний + документ в формате Overlay, который эти описания добавляет. Ещё при помощи Overlay можно консистентно поддерживать два видов описаний: для внутреннего использования и для внешнего. А ещё можно в спеку Overlay вынести типовые для всех ваших API вещи: ту же аутентификацию и, например, описание ошибок. А можно убрать из общедоступной спецификации внутренние методы или параметры. Поддержка нового формата пока ограниченная, но уже есть пара тулзов для встраивания в ваш CI/CD-пайплайн: отдельный тул openapi-overlays-js и ещё несколько в составе платформ для управления API. Ранее в этом году OpenAPI Iniriative выпустила также спецификацию The Arazzo (Гобелен) , это тоже интересная штука. Помните принцип HATEOAS от Роя Филдинга? Ответ API должен содержать в себе все необходимые ссылки для работы с этим API? Вот Arazzo — что-то в этом духе. Только не внутри каждого ответа, а вынесенное в отдельную спецификацию. Этот формат описывает workflow для API. То есть, в какой последовательности нужно вызывать ваши эндпоинты, чтобы достичь нужного результата. Вот она, новая жизнь юзкейсов! В общем, идеи, не взлетевшие за 25 лет, не дают покоя исследователям и появляются в новых инкарнациях. С другой стороны, почему нет, посмотрим, как оно заживет. Структурно спецификация Arrazo и правда похожа на формальное описание юзкейса: идентификатор, назначение, описание, входные параметры (inputs), предусловия (воркфлоу, которые должны быть выполнены до начала этого), шаги, ветвления при успехе/неудаче, результат выполнения (outputs). На каждом шаге мы можем получить результат вызова какого-то API (это могут быть API разных сервисов!), проверить эти результаты (не ошибка ли? есть ли нужные поля/значения?), сохранить ответ и перейти на другой шаг в зависимости от успеха или неудачи (есть операция goto). Что вам ещё нужно. Выглядит довольно перспективно — как легковесная замена BPEL, почти всех интеграционных сервисов типа MAKE (ну, нужно только добавить средства преобразования данных). Ну и для AI-решений, куда же без них: описываем цепочку вызовов разных LLM. Вообще идеи такие были и раньше: тот же BPEL и BPEL-for-REST, WS-CDL для SOAP, RESTalk — ну посмотрим, как заживет предложение от OpenAPI.