Рекомендации по работе в модуле "API / контракты"

Модуль «Описание API / контракты» по своей сути является упрощённой вариацией Swagger. Данный модуль предназначен для документирования условий обмена данными между сервисами и приложениями через API и является каталогизатором endpoints, упрощащим работу команды разработки. Модуль представлен категориями «API» и «Коды выхода».

Здесь собраны рекомендации по работе в модуле, которые позволят использовать его наиболее эффективно.

Категория «API»:

На первом уровне создавайте группы методов API, который может представлять собой микросервис или массив роутов. Создавайте элементы «Приложение API», которые станут связующими для методов и групп методов API.

Информационные модели конкретных методов API будут состоять из описания, route, программного обеспечения, схем данных входящих и данных ответа. В описание метода API можно внести не только backend-данные, но и API программы с точки зрения интерфейса.

Вносите как можно больше данных, чтобы другие участники процесса разработки смогли получить информацию в полноте. Это можно сделать как этапе создания элемента «API endpoint (Метод)», так и позднее (контекстное меню элемента → «Редактировать»).

Связывайте элементы «Приложение API» в категории «API» с элементами «Программа» из категории «Программное обеспечение».

Важно связать метод API с функциональной возможностью из категории «Функциональные возможности ПО», так так в большинстве случаев функциональная возможность обращается к определённому API. Эта связь будет видна в приложении «Данные» функциональной возможности и в приложении «Реестр связей» метода API.

Категория «Коды выхода»

Рекомендуем связывать элементы «API endpoint (Метод)» с кодами выхода из категории «Коды выхода». Эта связь будет отображаться в приложении «Данные» метода API и в приложении «Реестр связей» кода выхода, позволяя быстро перейти от одного элемента к другому.

Код выхода представляет собой конролируемый выход, при котором указывается конкретная ошибка для пользователя. Описание кодов выхода позволяет удобно реализовывать интернационализацию и давать пользователю исчерпывающую информацию. Используйте коды выхода для обработки исключительных ситуаций, когда приложение не переводится в состояние exception.

Код выхода обрабатывается приложением, которое выводит пользователю информацию и даёт возможность подать запрос.

Рекомендуем группировать коды выхода по приложениям, обозначаемым префиксами, равными 100.

Модуль будет активно развиваться и дорабатываться, в том числе с учётом рекомендаций пользователей.