APIOps as Code: Documenting the API Lifecycle with PlantUML

CI/CD automated how we ship code. APIOps automates how we ship APIs — the design, review, publish, and deprecate cycle that most organizations still run on meetings and wiki pages. This guide covers the lifecycle, the maturity stages, and how to document all of it as code.

BY THE WAY: Platform Economies — launching September 1, 2026.
Pre-order on Amazon — Kindle edition available now; paperback follows on September 1. Also available in 🇬🇧 UK, 🇩🇪 DE, 🇯🇵 JP, and 🇨🇦 CA. The APIOps cycle on this page is the operational engine from Part Four of the book.
Book page: mohammed-brueckner.com/platform-economies.

📚 Diagrams on this page are PlantUML. New to it? PlantUML with ArchiMate: Complete Guide · C4 diagrams with PlantUML

From CI/CD to APIOps
The APIOps Cycle
Maturity Stages
Documenting the Pipeline as Code
The Measurement Trap

From CI/CD to APIOps

CI/CD answered: how do we get code from laptop to production safely? APIOps answers a harder question: how do we get an API from idea to a managed, versioned, monetizable product — repeatedly, at scale, without a committee?

The gap is real. Most organizations have pipelines for code and process theater for APIs. Design happens in documents. Review happens in meetings. Publication happens when someone remembers. Deprecation happens never. The result: seventy percent of organizations track API volume, less than ten percent track API business value. They measure motion, not direction.

APIOps treats the API lifecycle like a pipeline: versioned specifications, automated linting and breaking-change detection, contract tests, catalog publication, and retirement policies — all as code, all in Git, all reviewable.

The APIOps Cycle

Six stages, one cycle — at a glance:

flowchart LR
    D["1. Design<br>OpenAPI spec in Git"] --> R["2. Review<br>linting, governance"]
    R --> B["3. Build &amp; Test<br>contract tests, mocks"]
    B --> P["4. Publish<br>catalog, docs, keys"]
    P --> O["5. Operate<br>monitor value, not uptime"]
    O --> E["6. Evolve / Retire<br>version, deprecate"]
    E -.->|"feedback loop"| D

The same cycle as PlantUML source — copy it, adapt it, put it in your repo:

@startuml
!theme plain
left to right direction
skinparam linetype ortho

title The APIOps Cycle

rectangle "1. Design\n(OpenAPI spec in Git)" as design #FDF6EC
rectangle "2. Review\n(linting, governance checks)" as review #FDF6EC
rectangle "3. Build & Test\n(contract tests, mocks)" as build #FDF6EC
rectangle "4. Publish\n(catalog, docs, keys)" as publish #FDF6EC
rectangle "5. Operate\n(monitor value, not just uptime)" as operate #FDF6EC
rectangle "6. Evolve / Retire\n(version, deprecate, sunset)" as evolve #FDF6EC

design -right-> review
review -right-> build
build -right-> publish
publish -right-> operate
operate -right-> evolve
evolve -up-> design : feedback loop

@enduml

The stage everyone skips is the feedback loop from 6 back to 1. APIs that never retire accumulate into the kind of landscape that makes migration programs necessary. Deprecation is a feature of the lifecycle, not a failure of the API.

Maturity Stages

Four stages, and most organizations sit at stage two believing they are at stage four:

Ad hoc. APIs happen inside projects. Discovery means asking around.
Standardized. Specs and a style guide exist. Compliance is manual — and therefore optional in practice.
Automated. Specs are linted in CI, breaking changes fail builds, the catalog publishes itself.
Product-managed. APIs have owners, roadmaps, and success metrics tied to business value.

What each stage looks like from the inside, how to tell where you actually are (as opposed to where the slide deck says you are), and what the jump from 3 to 4 costs — that is the measurement chapter of the book. One thing worth knowing now: the jump is not technical. It is the moment the organization starts treating APIs as products with customers instead of plumbing with consumers. That jump is a business-model decision, which is why it is a chapter in a book about platform economics and not a chapter in a Jenkins manual.

Documenting the Pipeline as Code

The APIOps pipeline itself deserves a diagram — this one in C4 notation, because the audience is the engineering team that builds it:

@startuml
!include <C4/C4_Container>
left to right direction

title APIOps Toolchain — Container View

Person(dev, "API Developer")

Container(repo, "API Spec Repository", "Git", "OpenAPI specs, lint rules, contract tests")
Container(ci, "CI Pipeline", "GitHub Actions", "Lint, breaking-change check, contract tests")
Container(catalog, "Developer Portal", "Backstage", "Catalog, docs, ownership")
Container(gateway, "API Gateway", "Kong/Azure APIM", "Keys, policies, analytics")

System_Ext(consumers, "API Consumers")

Rel(dev, repo, "Pushes spec changes")
Rel(repo, ci, "Triggers on pull request")
Rel(ci, catalog, "Publishes on merge")
Rel(ci, gateway, "Deploys config on merge")
Rel(consumers, catalog, "Discovers and subscribes")
Rel(consumers, gateway, "Calls APIs through")

@enduml

The two diagrams on this page live in the same repo as this article — which is the point. When the pipeline changes, the diagram changes in the same pull request. Documentation that cannot drift is the only documentation worth maintaining.

The Measurement Trap

The maturity stages fail quietly when organizations measure the wrong things. Endpoints shipped, requests per second, developer signups — activity metrics. A program can ship forty-seven endpoints and generate less value than one that ships three.

The compression-signal questions are different: what percentage of our APIs generate measurable business value? How many of our developers would pay if we charged? What is our revenue per API call? These are harder to put on a dashboard. They are the only ones that tell you whether your API program is a platform play or a cost center with good uptime.

If you want the diagnostic version of this: the Platform Compression Scorecard scores five signal categories in about five minutes, and API program health shows up in at least three of them.

Mohammed Brückner

Enterprise architect and author in Munich: PlantUML and ArchiMate guides, platform economics, MLOps with Databricks, and practical AI adoption — hands-on, no hype.