OpenAPI Skeletons And Resource Families — Первый bounded synchronous contract artifact

Версия: 1.0
Дата: 24.04.2026
Статус: Готов к обсуждению

Назначение документа

Этот документ фиксирует первый bounded слой для будущих OpenAPI-артефактов платформы.

Его задача — определить:

• какие resource families должны первыми получить formal synchronous contract shape;
• какие surface-ы эти ресурсы обслуживают;
• какие операции действительно нужны на первом implementation этапе;
• как resource families соотносятся с release units, truth boundaries и contract honesty.

Документ не является финальной OpenAPI-спецификацией. Он является skeleton-layer, по которому уже можно собирать более формальные schemas и endpoint catalogs.

Опорные документы

• API Contracts — Surface Contracts и правила внешнего взаимодействия
• Initial Contract Package — Первый implementation-ready пакет контрактов платформы
• Implementation Ready Breakdown — Первые release units, execution slices и порядок практической реализации
• Offer Pricing Booking Semantics — Семантика предложения, цены и бронирования
• Partner Finance And Clearing — Балансы, лимиты, взаиморасчёты и финансовая дисциплина партнёров
• Post-Booking Lifecycle — Изменения, отмены, инциденты и сопровождение после продажи
• Release Engineering And Migrations — Релизы, совместимость и эволюция схем

Почему Этот Документ Нужен Отдельно

Уже недостаточно иметь только:

• общий api-contracts.md;
• initial contract package;
• implementation-ready breakdown.

Нужен документ, который впервые говорит:

• какие synchronous resources реально формализуем первыми;
• какие методы нужны;
• где будут bounded endpoint families;
• какие вещи пока намеренно не открываем наружу.

Без этого команда либо слишком рано заморозит всё API целиком, либо начнёт стихийно строить endpoints по месту.

Главный Принцип

Первый OpenAPI skeleton должен быть:

• surface-aware;
• offer-centric, а не hotel-centric;
• quote-aware and booking-aware;
• tenant-aware and policy-aware;
• small enough to implement;
• honest enough to not over-promise.

Первые Resource Families

1. Search Context

Назначение

Формализовать вход в offer discovery.

Основные операции

• POST /search-contexts
• GET /search-contexts/{search_context_id}

Что Должно Возвращаться

• normalized search intent;
• correlation ids;
• search validity hints;
• pagination/session linkage where needed.

Что Пока Не Нужно

• слишком сложная session state machine;
• broad public search analytics endpoints;
• overly generic “hotel search for everything”.

2. Offer Discovery

Назначение

Формализовать bounded offer discovery and retrieval.

Основные операции

• GET /offers
• GET /offers/{offer_id}

Что Должно Быть Видно

• offer identity;
• property summary;
• high-level price view;
• publication state;
• freshness / revalidation hints;
• tenant-aware visibility.

Что Не Должно Утекать

• raw supplier payload;
• internal governance detail;
• hidden commercial internals not suitable for the current surface.

3. Quote

Назначение

Формализовать commercial fixation.

Основные операции

• POST /quotes
• GET /quotes/{quote_id}
• POST /quotes/{quote_id}/refresh

Что Должно Покрываться

• quote creation;
• quote retrieval;
• repricing-required visibility;
• invalidation/refresh path.

4. Booking

Назначение

Формализовать bounded booking commit surface.

Основные операции

• POST /bookings
• GET /bookings/{booking_id}
• POST /bookings/{booking_id}/cancel-requests

Что Должно Быть Видно

• booking intent result;
• current booking state;
• unknown external state if applicable;
• limited cancellation request baseline.

5. Post-Booking Cases

Назначение

Дать controlled visibility for post-sale service reality.

Основные операции

• POST /post-booking-cases
• GET /post-booking-cases/{case_id}
• GET /bookings/{booking_id}/post-booking-cases

Что Это Должно Покрывать

• support/disruption/cancellation/amendment baseline cases;
• actor-visible statuses;
• owner and pending/resolved semantics at the correct abstraction level.

6. Usage And Limits Signals

Назначение

Не строить full metering API сразу, но уже сделать contractually visible quota/limit states.

Основные операции

• GET /usage-profile
• GET /usage-profile/limits

Что Должно Быть Видно

• quota state;
• nearing limit;
• exhausted state;
• degraded profile flags;
• blocked-by-clearing or policy flags where surface-appropriate.

Surface Mapping

Internal Operational Surface

Может использовать:

• all first-wave resource families;
• richer fields;
• more mutation capabilities;
• more diagnostics-oriented views.

Agency Working Surface

Должен использовать:

• search contexts;
• offers;
• quotes;
• bookings;
• bounded post-booking cases.

Partner API Surface

Первый bounded partner package должен использовать только:

• offer discovery;
• quote;
• booking;
• usage/limits signals.

Post-booking visibility здесь может быть уже, но в значительно более ограниченной форме.

Resource Families By Release Unit

RU-3 Offer And Publication Slice

Нужны:

• search-contexts
• offers

RU-4 Commercial And Quote Slice

Нужны:

• quotes

RU-5 Booking Commit Slice

Нужны:

• bookings

RU-6 Post-Booking And Clearing Slice

Нужны:

• post-booking-cases
• usage-profile and limit signals at least in bounded form

Common OpenAPI-Level Concerns

Каждая первая resource family должна уже поддерживать:

• correlation identifiers;
• tenant/actor context where relevant;
• honest error model;
• explicit freshness/revalidation semantics where relevant;
• pagination where list shapes exist;
• versioning note.

What Must Stay Out Of The First OpenAPI Skeleton

Пока не нужно включать:

• full internal operator admin surface;
• complete governance workflows;
• settlement and reconciliation full surface;
• advanced tour-builder full contract family;
• generic “one API for everything”.

Suggested Next Formalization Layer

После этого skeleton-документа логично делать уже более формальные артефакты:

1. openapi-envelope-and-error-model.md
2. partner-api-first-wave-openapi-outline.md

Краткий Итог

Этот документ фиксирует первый bounded synchronous contract layer:

• не весь API целиком;
• не финальную OpenAPI спецификацию;
• а первые resource families, которые действительно соответствуют первым release units и уже могут быть formalized without lying about platform maturity.

Уточнение под Фазы 4–6 (28.04.2026) — каноничные resource families и связи

Документ опубликован 24.04.2026 (Фаза 3) как первый sync contract baseline (8 resource families). После Фаз 4–6 опубликованы 12 новых каноничных доменов; resource families расширяются.

Каноничные новые resource families (Фаза 4–6)

Resource family	Каноничный документ
Payment (PaymentIntent, Refund, Chargeback, PayoutBatch, PaymentMethod)	reference/payment-domain.md
API as Product (Partner, PartnerApplication, ApiKey, Tier, Quota)	reference/api-as-product.md
Search & Discovery (SearchProjection, RankingPolicy, SearchFacet)	reference/search-and-discovery.md
Notifications (NotificationTemplate, ConsentLog, WebhookSubscription)	reference/notification-and-communication.md
Media & Content (MediaAsset, ContentBundle, ContentTranslation)	reference/media-and-content.md
i18n (SupportedLanguage, SupportedCurrency, FxRateSnapshot)	reference/internationalization-and-localization.md
Analytics (AnalyticsExport, partner-facing dashboards)	reference/analytics-and-bi.md
A/B Testing (Experiment, FeatureFlag, ExperimentAssignment)	reference/ab-testing-platform.md
Booking State Machine (14 состояний, transitions, recovery)	reference/booking-state-machine.md
Tour Builder Operational (CompositionRule, TourBookingTransaction, DriftEvent)	reference/tour-builder-operational-model.md
Multi-Tenant Isolation (IsolationProfile, IsolationBoundaryCheck, CrossTenantAccess)	reference/multi-tenant-isolation-strength.md
Compliance (DSR API, ConsentLog, BreachNotificationLog)	reference/compliance-and-legal.md

Связь с OpenAPI-first proposal

development/proposal-openapi-first-polyglot-codegen.md — open proposal: каноничный layout /api/openapi/platform-v1.yaml, /api/openapi/partner-v1.yaml, /api/openapi/internal-v1.yaml. OpenAPI 3.1, Spectral linting, code generation через oapi-codegen (Go), openapi-typescript + openapi-fetch (TS).

Связь с api-contracts.md

reference/api-contracts.md (Фаза 3 + Фаза 10 уточнение) — расширение Surface Map с 5 на 6 surfaces (добавлен Tour Builder Closed Surface). При создании OpenAPI specs — учитывать 6 surfaces.

Связь с двумя ortogonal taxonomies

Surface Contracts (layers.md, 6 surfaces) × Client Surfaces (clients.md, 6 surfaces) — две ortogonal таксономии. Partner API contract обслуживает 2 client surfaces (Machine + UI/SDK). См. overview/layers.md, уточнение под Фазу 7.

Уточнение выполнено через no-destruction.