<HTTP-метод> — <Название операции>

Когда какой блок включать. Обязательные блоки API-операции — Назначение, Metadata, Актор и доступ, HTTP-контракт, Входные данные, Модель ответа, Алгоритм, Ошибки и failure modes, Совместимость и наблюдаемость, Связанные документы. Условные блоки (Побочные эффекты, Диаграмма, строки record-level / tenant / audit) включай только когда им есть что сказать — пустой блок удаляй. Матрица блоков и уровень изложения — Уровень изложения ТЗ.

Назначение

2–4 предложения простым языком: бизнес-цель операции, кто её вызывает, что получает на выходе. Без деталей реализации и без ссылок на правила авторинга. Читатель за 10 секунд должен понять, зачем этот эндпоинт существует.

Metadata

Поле	Значение
Сервис/контекст	<context>
API area	public / admin / internal / callbacks
Feature group	<feature-group>
Статус	draft / approved / deprecated
Документ	docs/06-services/<context>/api/<area>/<group>/<method>-<operation>.md

Актор и доступ

Проверка	Значение
Actor type	Anonymous / User / Operator(Admin) / System / ExternalSystem
Auth policy / Permissions	<policy / permission list или none>
Scope (RBAC)	<платформа / организация / группа проектов / проект>
Record-level	<владелец/группа — только если применимо>
Tenant isolation	TenantId в каждом запросе
Audit	<create/update/delete/read-sensitive — только если применимо>

HTTP-контракт

Поле	Значение
Method	GET / POST / PUT / PATCH / DELETE
Route	/api/v1/<route>
Success status	200 / 201 / 202 / 204
Idempotency header	<header — только если применимо>
Correlation	сквозной trace через заголовок traceparent

Входные данные / параметры запроса

Единая секция: HTTP-источник (route/query/body/header/identity) + типизированное поле модели запроса.

Поле	Источник	Тип	Обязательность	Валидация / Ограничения	Безопасность
TenantId	identity claims	Guid	Да	Required	Tenant isolation
<FieldName>	route/query/body/header	<TypedValue>	Да/Нет	<format/min/max/enum/reference id>	<mask/exclude>

Модель ответа <ResponseModelName>

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

Поле	Тип	Обязательность	Источник	Masking	Описание
<FieldName>	<Type>	Да/Нет	<entity/projection/computed>	<rule>	<описание>

Алгоритм

Нумерованные бизнес-шаги: happy path и все ветки отказа. Для каждого шага — какую сущность по каким условиям получаем/проверяем и что решаем; при отказе — какой код ошибки возвращаем (коды дублируются в таблице «Ошибки»). Неприменимый шаг опускается целиком. Тривиальный CRUD описывается одним абзацем без нумерации и без диаграммы. Полная структура шагов — в Правилах Документирования Алгоритма.

1. Контекст и доступ. Кто выполняет операцию (актор), в каком scope/tenant, какие права требуются.
2. Проверка входа и предусловий. Формат/диапазоны/enum входных полей; существование сущности по её бизнес-ключу/id; допустимость состояния (перечислить допустимые статусы); принадлежность/scope (tenant, владелец/группа). Для каждой ветки нарушения — свой код ошибки.
3. Что читаем. Какие сущности и по каким условиям загружаем и зачем; списки/поиск — по каким фильтрам, сортировке, пагинации.
4. Бизнес-правила и переходы. Инварианты (INV-*), переходы статуса From → To с условием, расчёты; маппинг поле-в-поле: для каждого выходного/сохраняемого поля — источник (вход / загруженная сущность / вычисление).
5. Что меняется (только операции записи). Какие сущности создаются/обновляются/удаляются и в каком порядке; конкурентный доступ — как бизнес-условие («правка не должна затирать чужую»). Все изменения применяются в одном согласованном изменении (атомарно).
6. Результат. Что возвращает операция (модель/статус); для чтения — актуальность (freshness) и правила маскирования чувствительных полей.

Шаг записи (5) в read-операциях опускается. Публикацию событий и внешние вызовы описывай в «Побочных эффектах» (если они есть).

Диаграмма

Опциональна: рисуй только для нетривиального поведения; для простого CRUD — опусти. Участники — бизнес / доменные роли.

Побочные эффекты

Условный блок: включай, только если операция публикует события, делает внешние вызовы, обновляет проекции/поиск или шлёт уведомления. Если ничего этого нет — секцию опусти целиком (не оставляй таблицу с none).

Тип	Детали
Интеграционные события	<имя события / топик / ключ>
Внешние вызовы	<система / таймаут / retry>
Проекции / поиск	<проекция / индекс>
Уведомления	<канал / шаблон>

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
<ErrorCode>	<status>	<condition>	<safe message>	<retry/no retry>

Совместимость и наблюдаемость

• Новые optional поля — без breaking change; удаление/переименование/смена типа — breaking (migration + rollout).
• Logs/metrics/traces на ключевых точках (приём запроса, отказы валидации, публикация событий); correlation — сквозной trace через traceparent.

Обратные ссылки

Автоссылки: где используется этот документ.

• API (4): Identity Admin API — реестр методов и общие правила области, Identity Agent API — реестр методов и общие правила области, Rewards API — реестр операций и общие контрактные модели, Wallet API — реестр операций и общие контрактные модели
• Use Cases (3): UC-RWD-001. Застройщик настраивает правила вознаграждений агентов, UC-SEL-001. Создание подборки из текущего избранного, UC-SEL-003. Аноним открывает подборку по публичной ссылке
• index.md (4): Шаблоны Документации, Calendar Service, Messenger Service, Notifications Service
• algorithm-documentation-rules.md (1): Правила Документирования Алгоритма
• documentation-file-templates.md (1): Индекс Шаблонов Документации
• command-query-template.md (1): Внутренняя операция: <НазваниеОперации>
• event-contract-template.md (1): Event Contract: <event.name> ()

Связанные документы

• Сущности: <entity links>; события: <event-contract links>; клиент: <openapi-client link>.