API Governance & Versioning¶

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

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	Code-first C# contracts (ServiceModel.Grpc, no .proto)
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 / code-first gRPC contract 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 code-first gRPC
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.