Industrialise

Industrialising an API platform means putting three things through versioned pipelines rather than through consoles: the configuration of the platform itself, the exposure of each API, and the documentation. The three axes have different rhythms and different owners, and conflating them produces pipelines nobody uses.

The manual configuration they replace is the leading cause of incidents in the field: no history of why, no rollback, environments that drift apart until staging proves nothing any more.

Axis 1: the platform

The base layer: accounts and roles, entitlements, certificates and TLS, domains, data plane deployment, network. It changes rarely, it is critical every time, and it belongs to the platform team.

The tooling is infrastructure tooling: the vendor's Terraform or OpenTofu provider, the administration API, the CLI inside the pipelines. The criterion for choosing a product is the coverage of its provider: whatever can only be driven from the console will end up configured in the console. Certificates deserve the strictest treatment on this axis: inventory, expiry alert at thirty days, renewal rehearsed in a test environment. The silent expiry of a partner certificate remains a recurring cause of incidents on mTLS flows.

Secrets never live in the repositories: vault, resolution at deployment time, rotation without redeployment.

Axis 2: exposing an API

The daily work: publishing an API, changing it, promoting it between environments. It belongs to the product teams, within the boundaries set by the platform, and it is the axis the term APIOps covers.

OpenAPI contract

In the service repository, with the policies

Automated pipeline

Validation

Governance rules

Test

Contract, security, regression

Publication

Through the control plane API

drift check

Production

The actual state, compared with the declared one

The contract and the policies of the API live in the service repository, next to the code: a change to the service and a change to its contract form a single review. The pipeline validates, with the executable governance rules, compatibility included, tests, then publishes through the control plane API. Promotion between environments moves the same artefact, it retypes nothing: what was tested in staging is what goes to production, apart from the environment parameters, which are versioned too.

Axis 3: the documentation

Documentation is not written in the portal, it is published there. The axis 2 pipeline feeds the portal: reference generated from the contract, examples run by the tests before they are shown, a changelog produced by comparing the versions of the contract, deprecations flagged from the lifecycle.

What is still written by hand, getting started guides, an explanation of the model, lives as files in the repository and follows the same review path as the rest. The portal has no content editor: it is the only known way to still have accurate documentation a year later.

Drift detection, across all three

A pipeline is not enough: as long as a manual change remains possible, it will happen under the pressure of an incident, and the repository will silently stop describing reality. The loop closes with a regular comparison between the declared state and the actual state, on all three axes: drift is flagged, then either written back into the repository or reverted by the automation.

The corollary is organisational: remove write access in production, platform team included, keeping an emergency path that is logged and followed by a write back. Maturity is measured there: a pipeline that coexists with an open console has industrialised nothing.

Where to start

Export what exists into the repositories and make that the reference. Wire automated publication onto a pilot scope. Turn on drift detection in report-only mode. Close the manual path scope by scope. In that order: detection before closure, otherwise the closure does not hold.