Skip to content

API Governance & Versioning

This page consolidates the rules that keep every API across the factory consistent, evolvable, and safe to consume. The concrete inventory of APIs lives in the API Catalog; each platform's apis.md page documents its own surface. This page defines the governance those pages conform to.

Target Architecture — Final-State Design

APIs are contract-first and generated. The API Designer Agent produces contracts; the API Gateway Generator Agent and templates produce conformant implementations; governance policies enforce the rules below at design time and in CI.

API styles

Style Used for Standard
REST / JSON Public and cross-platform synchronous APIs OpenAPI 3.x, resource-oriented, standard HTTP semantics
gRPC High-throughput internal service-to-service Proto3 contracts, versioned packages
Async / events Decoupled cross-platform communication Canonical Event Envelope, Event Catalog 
flowchart LR
    client["Client / Other Platform"] -->|REST + JWT| gateway["API Gateway"]
    gateway -->|policy + routing| svc["Platform Microservice"]
    svc -->|gRPC| svc2["Internal Service"]
    svc -->|events| bus["Service Bus"]
    gateway -.->|OpenAPI| catalog["API Catalog"]
Hold "Alt" / "Option" to enable pan & zoom

Design standards

  • Contract-first — OpenAPI/proto definitions are authored (or generated) and reviewed before implementation; they are the source of truth.
  • Resource-oriented REST — nouns for resources, standard verbs (GET/POST/PUT/PATCH/DELETE), correct status codes, consistent error shape (RFC 7807 problem details).
  • Naming — paths, fields, and operations follow the Naming Conventions; JSON uses camelCase.
  • Pagination, filtering, sorting — standardized query conventions for collection endpoints.
  • Idempotency — unsafe operations accept an idempotency key where retries are expected; aligns with the event envelope idempotency model.
  • Multi-tenancy — tenantId is derived from the validated JWT, never from the request body; every endpoint is tenant-scoped (see Multi-Tenancy).

Versioning

Rule Detail
Scheme Semantic versioning; major version in the URL path (/v1/, /v2/) for REST, versioned packages for gRPC/proto
Backward compatibility Additive changes only within a major version; never repurpose or remove a field
Breaking changes Require a new major version running side-by-side with the previous one
Event versioning New eventType (e.g. ArtifactCreatedV2) or additive payload with bumped cs-schema-version; consumers tolerate unknown fields
Compatibility checks Enforced by contract tests in CI before promotion

Deprecation lifecycle

flowchart LR
    active["Active"] --> deprecated["Deprecated<br/>(announced + Sunset header)"]
    deprecated --> sunset["Sunset<br/>(read-only / warnings)"]
    sunset --> retired["Retired<br/>(removed)"]
Hold "Alt" / "Option" to enable pan & zoom
  • Deprecation is announced with a timeline; responses carry Deprecation and Sunset headers.
  • A deprecated version remains supported for a defined window before retirement.
  • Consumers are identified via the API Gateway and notified; usage is tracked to confirm safe retirement.
  • Deprecation and retirement decisions that affect consumers are recorded as an ADR.

Gateway policy

The API Gateway is the single managed entry point and enforces cross-cutting policy so services stay focused on domain logic:

Concern Policy
Authentication OAuth2/JWT validation (OpenIddict); reject unauthenticated requests
Authorization Coarse RBAC at the edge; fine-grained ABAC in services (see Security Architecture)
Rate limiting / throttling Per-tenant and per-client quotas; protects against abuse and noisy neighbors
Routing & versioning Route by path version; support side-by-side major versions
Observability Inject/propagate traceId; emit request metrics and logs
Request validation Schema validation and payload limits at the edge

Governance & ownership

  • Each API has a single owning service/bounded context (see the owning platform's apis.md).
  • New and changed contracts pass an API design review (automated by agents, policy-gated by Governance / Security / Compliance).
  • The API Documentation Agent keeps published docs in sync with the contract.

Pillar alignment

  • Traceability — every API call propagates traceId/correlationId and is correlated to downstream events and artifacts.
  • Reusability — gateway, client, and contract scaffolding come from templates and ConnectSoft.Extensions.* libraries.
  • Autonomy — contracts, gateways, clients, and docs are agent-generated and validated.
  • Governance — versioning, deprecation, and rate limits are policy-enforced and ADR-recorded.
  • Observability — gateway emits standardized request telemetry.
  • Multi-tenant scale — tenant scoping and per-tenant quotas are enforced at the edge.