API Architect: Portfolio Contracts and Governance

Wrote docs/architecture/api-architect/00-overview/api-architect-overview.md and docs/architecture/api-architect/verification/fitness-self-check.md. Complete API estate governance specification establishing mandatory endpoint registration, shared error and pagination conventions, stability tiers, and retirement verification.

skill: api-architect

API Estate Architecture: Open Banking and Treasury Portfolio [API-PORTFOLIO-001]

Summary

This specification establishes cross-service API contracts, interface governance, and evolution standards across the Open Banking and Treasury API Estate under run ID api-portfolio-gov-001. The portfolio encompasses 140 synchronous internal and partner-facing APIs across banking, lending, settlement, and treasury services. It decisively eliminates the uncoordinated removals and interface fragmentation demonstrated in incident INC-3109 (where Settlement Service deleted an unversioned endpoint without deprecation notice, breaking two dependent lending squads) and resolves the presence of three incompatible error shapes and four disparate pagination patterns across engineering squads.

The architecture enforces

1. Mandatory pre-routing registration requiring every API to declare an owning team, stability tier, consuming clients, and a canonical OpenAPI 3.1 contract in the enterprise catalog before gateway routing is provisioned;
2. Automated enforcement of shared conventions via CI contract linting (RFC 7807 problem details error format, cursor-based collection pagination using first and after, and URI major versioning /v{major}/);
3. Formal stability tiers (experimental, stable, partner) with explicit compatibility and notice guarantees;
4. Telemetry-driven retirement requiring 0 requests for 30 consecutive calendar days measured at the ingress gateway before any endpoint can be decommissioned.

Detailed Description

Operating 140 synchronous APIs across autonomous feature squads without binding contract governance leads to silent breaking changes, integration sprawl, and operational fragility. When conventions exist solely as markdown style guides or wiki pages, compliance varies by team. Furthermore, when endpoints can be published or modified without registering consumers, producer teams cannot predict the blast radius of changes.

API Lifecycle & Governance Pipeline
                 │
                 ▼
[ API Registry Admission Gate ]
  ├── 1. Declared Owner & Contact Channel
  ├── 2. Stability Tier Classification (Experimental / Stable / Partner)
  ├── 3. Canonical OpenAPI 3.1 Specification in Git Registry
  └── 4. Registered Consumer Inventory
                 │
                 ▼ (CI Automated Validation)
[ CI Contract Linter & Spectral Rule Engine ]
  ├── RFC 7807 Problem Details Schema Gate
  ├── Cursor Pagination Format (`first` + `after`) Gate
  └── URI Major Versioning (`/v{major}/`) Path Gate
                 │
                 ▼ (Deploy & Runtime Enforcement)
[ Ingress Gateway Policy & Observability Engine ]
  ├── Dynamic Route Ingestion from Registry Metadata
  ├── Gateway Error & Header Normalization
  └── Per-Consumer Usage Telemetry (Retirement Oracle: 0 calls / 30 days)

Alternatives rejected

Contracts and Invariants

Registration Requirement [RR-1]
  Before any API endpoint is routable at the ingress gateway, the producer must register in the
  enterprise API catalog: owner team identity, stability tier, expected consumers, and a canonical
  OpenAPI 3.1 document. Routable deployment without valid registration is blocked at gateway admission.

Conventions and Enforcement [CE-1]
  Shared API conventions are enforced deterministically in CI pipeline contract tests and at the gateway:
  1. Error responses must strictly adhere to RFC 7807 Problem Details (application/problem+json).
  2. Collection pagination must use cursor-based traversal with `first` (integer limit) and `after` (opaque cursor).
  3. Protocol versioning must use URI major versions (/v1/, /v2/); minor and patch changes must remain backward-compatible.
  4. Authentication must use OAuth 2.0 Bearer tokens with route-level scopes verified by gateway policy.

Stability Tiers [ST-1]
  All exposed interfaces must declare exactly one stability tier:
  - experimental: May change or be removed without notice; must be routed under the path prefix `/experimental/`.
  - stable: Backward-compatible within the same major version; minimum 6-month formal deprecation notice.
  - partner: Contractual backward compatibility; minimum 12-month formal deprecation notice and assigned migration advocate.

Evidence-Driven Retirement [ER-1]
  An endpoint in deprecated state cannot be retired or unrouted until the gateway per-consumer telemetry
  records exactly 0 requests across 30 consecutive calendar days. Calendar expiration alone is insufficient.

Ownership and Handoffs

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against API estate governance standards:

Registration Gate: PASS. Zero unowned endpoints routable; registry declaration mandatory before gateway provisioning.

Convention Enforcement: PASS. Problem details, cursor pagination, and versioning enforced by CI and gateway filters.

Deprecation Rigor: PASS. Deprecation requires per-consumer usage proof (0 requests / 30 days), preventing repeat of INC-3109.

Open Decisions

• DEC-APIGOV-01: Sarah Chen to determine whether internal service-to-service calls bypassing the main ingress gateway must enforce RFC 7807 problem details via shared middleware libraries (Owner: Sarah Chen).

Next steps

1. Sarah Chen (Architecture Guild) publishes the canonical Spectral ruleset for RFC 7807 and cursor pagination into the shared CI pipeline repository.
2. Elena Rostova (API Ecosystems) audits existing 140 APIs to catalog undeclared consumer dependencies and register them in the API catalog.
3. Gateway Platform team enables per-consumer route telemetry collectors to establish baseline traffic metrics across deprecated endpoints.

skill: api-architect

Open Banking and Treasury API Portfolio — Fitness Self-Check [API-PORTFOLIO-FIT-001]

Summary

This fitness self-check evaluates the API estate architecture against three critical red-capable domain failure probes: shared mutable ownership, leaky abstraction, and implicit coupling. All targeted probes pass by design construction. A self-check is supporting evidence, never the authoritative gate. Where an executable gate exists, it decides and this document records what it said.

Detailed Description

Residual Risk

• Squads operating internal legacy services may continue using older internal libraries that emit custom error formats until service redeployment. Accepted by Sarah Chen pending quarterly modernization milestones.

Traceability

Verification

No validator was supplied, so no command was run.

Open Decisions

None.

Next steps

1. Integrate synthetic probes FIT-1, FIT-2, and FIT-3 into the master CI pull-request validation workflow.
2. Schedule automated bi-weekly scans against all registered OpenAPI specs to detect leaky internal database abstractions.
3. Establish weekly deprecation telemetry reviews with Elena Rostova for endpoints approaching 30 consecutive zero-traffic days.