Контракты

Что это

Контракт — описание операции API, принадлежащее объекту. Каждый контракт описывает одну операцию: эндпоинт, метод, тело запроса и другие параметры, зависящие от протокола.

Контракты объекта отображаются на вкладке API (для сервисов, баз данных и очередей сообщений).

Свойства контракта

Свойство	Описание
Название	Имя операции (до 128 символов)
Описание	Что делает операция
Протокол	Тип взаимодействия (REST, gRPC, Kafka и др.)
Поля протокола	Зависят от типа — см. Поля протоколов
Тело	Схема или пример запроса в формате JSON, XML, Proto, SQL и др.

Примеры контрактов по протоколам

Протокол	Название	Поле 1	Поле 2	Тело
REST	getUserById	GET	/api/users/	JSON
gRPC	CreateOrder	unary	OrderService/CreateOrder	Proto
GraphQL	getProducts	query	getProducts	JSON
Kafka	publish-events	publish	user-events	JSON
PostgreSQL	getActiveUsers	SELECT	users	SQL

Создание контрактов

Контракты можно создавать двумя способами:

Вручную

На вкладке API объекта можно добавить контракт, указав протокол, название, поля и тело запроса.

Импорт из спецификации

Контракты можно импортировать из внешних спецификаций. При импорте система автоматически создаёт контракты на основе описания операций в файле.

Поддерживаемые форматы — см. Контракты и импорт.

Рекомендация

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

Связь с действиями в связях

При создании действия в связи можно выбрать контракт объекта. В этом случае поля действия заполняются из контракта. Действие может дополнять или переопределять данные контракта.

Один контракт можно использовать в нескольких связях — например, если к сервису обращаются несколько других объектов по одному и тому же эндпоинту.

Действия

Создание контракта

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

Редактирование контракта

Участник команды с ролью редактора или выше может изменить любые свойства контракта.

Удаление контракта

Участник команды с ролью редактора или выше может удалить контракт.

Примечание

• При удалении контракта действия в связях сохраняются, но теряют привязку к контракту
• При удалении связи контракты объекта не удаляются

Права доступа

Действие	Наблюдатель	Редактор	Администратор	Владелец команды	Владелец организации
Просмотр контрактов	✓	✓	✓	✓	✓
Создание контракта		✓	✓	✓	✓
Импорт контрактов		✓	✓	✓	✓
Редактирование контракта		✓	✓	✓	✓
Удаление контракта		✓	✓	✓	✓