platform-api-docs

Conventions

Versioning Strategy

• APIs are versioned using folder structure (v1, v2, etc.)
• New versions are added without breaking existing ones
• Older versions may be deprecated but remain accessible
• Every API publishes one document per service, on one URL. Nexus Flow uses nexus-flow/v1-<service>.yaml; there is no combined v1.yaml, and there is no latest.yaml anywhere — sos-admin and tenant-management had one until 2026-09-18 and both had drifted from the v1.yaml they were documented as aliasing.
• Removals and deprecations are recorded in deprecations.md and in the owning repository’s CHANGELOG.md, at the time the change is made — not afterwards.

Guidelines

• Use kebab-case for file and folder names
• Follow OpenAPI 3.x standards
• Ensure backward compatibility for existing versions

Contract parity

scripts/spec-parity.py compares each published contract’s surface — method + path, parameter names included — against the API repo’s committed generated document. It ignores descriptions, examples, servers and info.version, because the published YAML is deliberately hand-authored prose over the same surface.

python3 scripts/spec-parity.py            # every service with a generated document
python3 scripts/spec-parity.py flows      # one service

Exit 0 when every checked contract matches. Run it before promoting to an environment and record the result with the release — see Foundational/shared-library-and-release-standards.md §9.

Health routes (/<service>/health, /live, /ready) are exempt: they are registered outside API versioning, so they cannot be expressed under a server base ending /<service>/v1. Their absence is by construction, not drift.

It covers the eight NexusFlow services whose published path is the path the service serves — all of which are in parity as of 2026-09-16.

It deliberately does not cover sos-admin and tenant-management. Their contracts and their code are both correct and cannot be reconciled by stripping a prefix: tenant-management emits /tenants/access-controls/v1/... while the published contract says /tenant-man/..., because the gateway rewrites /tenant-man/v1 onto the service. Each document is right from its own end of that rewrite. Comparing them needs a rewrite-aware check rather than another entry in the table.