Перейти к основному содержимому

API Metering And Usage Governance — Учёт потребления, квоты и дисциплина использования

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

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

Этот документ фиксирует metering and usage governance как обязательный домен API-платформы.

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

  • как платформа измеряет использование внешних и управляемых surface-ов;
  • какие quota, limit and fairness rules действуют для партнёров и tenant-ов;
  • как consumption economics связаны с supplier cost, partner value и platform protection;
  • как usage governance влияет на allow/deny/degrade decisions.

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

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

Для industrial B2B API-platform недостаточно просто ограничить RPS на gateway.

Платформа должна понимать:

  • кто и сколько ищет;
  • кто и сколько квотирует;
  • кто создаёт booking;
  • сколько supplier cost создаёт конкретный потребитель;
  • каково соотношение search / quote / booking;
  • какой tenant разрушает shared economics без полезной конверсии.

Это уже не infra throttling, а часть product and business governance.

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

Измеряться должно не только “сколько HTTP-запросов пришло”, но и:

  • сколько platform cost они породили;
  • сколько supplier pressure они создали;
  • сколько valid commercial opportunities они дали;
  • какое поведение партнёра является здоровым, а какое токсичным.

Основные Классы Metering​

1. Request Metering​

  • total requests;
  • method/family distribution;
  • per-surface usage;
  • per-tenant and per-credential usage.

2. Search And Discovery Metering​

  • search volume;
  • heavy filter usage;
  • pagination depth;
  • repeated low-value searches;
  • destination/date spam patterns.

3. Quote Metering​

  • quote creation volume;
  • expired quote ratio;
  • repricing rate;
  • quote-to-book ratio.

4. Booking Metering​

  • booking attempts;
  • successful bookings;
  • abandoned booking flows;
  • failed booking ratio;
  • cancellation-heavy partners.

5. Supplier Pressure Metering​

  • upstream calls caused by tenant;
  • expensive suppliers usage share;
  • revalidation pressure;
  • cache bypass pressure;
  • disruption induced by bad usage patterns.

Look-To-Book И Аналогичные Экономические Метрики​

Платформа должна уметь удерживать как минимум:

  • search-to-quote ratio;
  • quote-to-book ratio;
  • search-to-book ratio;
  • supplier-call-to-book ratio;
  • cancellation-adjusted booking quality ratio.

Эти метрики должны использоваться не только для analytics, но и для policy decisions.

Usage Governance Outcomes​

Metering without consequences недостаточен.

Платформа должна уметь применять:

  • soft warning;
  • quota exhaustion notice;
  • degraded rate profile;
  • forced review;
  • temporary restriction;
  • commercial renegotiation trigger;
  • full block for abusive usage.

Tenant-Aware Usage Policies​

Разные tenant-ы могут иметь разные envelopes:

  • sandbox profile;
  • early-integration profile;
  • production partner profile;
  • premium distribution profile;
  • high-risk restricted profile.

Surface Consequences​

Partner API​

Должен честно отражать:

  • quota state;
  • nearing limit;
  • hard exhaustion;
  • degraded mode;
  • fairness restriction;
  • retry policy after throttle.

Internal Operations​

Должны видеть:

  • who is expensive;
  • who is noisy;
  • who is high-value but spiky;
  • where supplier pressure is accumulating;
  • where commercial review is needed.

Observability И Usage Governance​

Metering не должен жить отдельно от observability.

Платформа должна коррелировать:

  • tenant;
  • credential;
  • surface;
  • supplier impact;
  • quote/book consequences;
  • incidents caused by abusive or pathological usage.

Что Должно Быть Сделано Дальше​

После фиксации этого домена нужно:

  • синхронизировать api-contracts, tenancy-and-identity, clients, suppliers, observability;
  • определить persistent usage facts and aggregation windows;
  • сформировать quota taxonomy;
  • связать usage governance с tenant enablement and partner commercial terms.

Уточнение под Фазы 4–6 (28.04.2026) — связи с api-as-product, economic-model, isolation​

Документ опубликован 24.04.2026 в Фазе 3 как baseline для metering. После Фаз 4–6 каноничной архитектуры опубликованы документы, которые используют этот metering как основу или расширяют его. Эта секция фиксирует обязательные связи.

Связь с программным интерфейсом как продуктом​

reference/api-as-product.md (Фаза 4) прямо опирается на этот документ:

  • 4 тарифных уровня (Free / Starter / Professional / Enterprise) определяют квоты и лимиты, которые применяются через метрики этого документа;
  • partner certification flow проверяет, что партнёр умеет обрабатывать quota signals из этого документа;
  • billing цикл партнёра (subscription + usage) использует данные metering как авторитетный источник.

Каноничная связь: тарифные уровни api-as-product.md задают envelope, metering этого документа измеряет фактическое потребление, economic-model.md превращает данные в счёт.

Связь с экономической моделью​

reference/economic-model.md (Фаза 4) использует метрики этого документа как:

  • cost driver для расчёта unit-economics;
  • revenue driver для partner_api_usage revenue stream;
  • complexity_score (search, quote complexity) — множитель в формуле динамического ценообразования.

При расчёте формулы динамической тарификации платформенных услуг partнёра — данные этого документа авторитетны.

Связь с уровнями тенантной изоляции​

reference/multi-tenant-isolation-strength.md (Фаза 5) — три уровня изоляции (logical / dedicated_compute / dedicated_infrastructure) не отменяют metering, но создают разные cost basis:

  • logical tenants — стандартный metering как описано в этом документе;
  • dedicated_compute tenants — metering применяется к выделенному namespace, отдельные envelope;
  • dedicated_infrastructure tenants — metering для billing + capacity tracking + дополнительная плата dedicated_infrastructure_fee.

IsolationBoundaryCheck (continuous automated проверка cross-tenant access) — отдельный канал, не часть metering, но генерирует metric cross_tenant_access_attempts per tenant.

Связь со SLA-моделью​

operations/sla-and-on-call-model.md (Фаза 6) использует metrics этого документа для расчёта SLI:

  • availability per surface — на основе request_metering total + error rate;
  • latency p95 — измеряется на gateway + agreggregируется per tenant;
  • webhook delivery — на основе webhook_delivery metering;
  • search freshness — на основе search response time + cache hit ratio;
  • booking confirmation latency — на основе booking metering;
  • unknown_external_state ratio — отдельный SLI (target менее 1%);
  • payment success — на основе payment metering;
  • restoration success — на основе DR drill metering;
  • MTTR — на основе incident metering;
  • support response time — на основе support ticket metering.

Связь с disaster-recovery-and-capacity​

operations/disaster-recovery-and-capacity.md (Фаза 6) использует metering для:

  • capacity forecasting — данные роста потребления per tenant;
  • planning peak loads — sезонные пики, региональные пики, партнёрские пики;
  • alerting на превышение headroom — 30–40% headroom над baseline.

Capacity events (capacity.threshold.warning_triggered, capacity.threshold.critical_triggered) — отдельный поток, опирающийся на metering.

Связь с программным интерфейсом для разработки контракта​

development/proposal-openapi-first-polyglot-codegen.md — proposal зафиксирует OpenAPI-first для polyglot. Metering должен быть формализован в OpenAPI:

  • response headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset;
  • response code 429 при rate limit exceeded;
  • standardized error envelope для quota-related errors.

Каноничный итог уточнения и связанная документация​

Этот документ остаётся базовым slой metering и usage governance. Расширения и реализация:

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