API Ops

API Ops is the practice of changing APIs through a reviewed, automated pipeline. The API contract (an OpenAPI or AsyncAPI description) and the gateway configuration (routes, authentication, limits) live in Git. Each change is a pull request: gates lint it, compare it with the previous contract for breaking changes and run tests; after approval, a pipeline generates the gateway configuration and promotes the same commit through environments. Telemetry shows who calls which version. It serves API platform teams, backend engineers who publish APIs, and API product managers who promise consumers that an API will not break under them.

Where to start. Beginners: the glossary and Lab 1. Engineers: the contract gate and reference implementation. Leaders: the decision framework and judgement call.

Hand-publishing works for one API. Trouble arrives with the tenth API, the fourth team and the first external partner:

• Four truths that disagree. Documentation, contract, gateway and code diverge when people fix production in a portal; Microsoft’s reference architecture requires such changes to be extracted back into Git through a reviewed pull request^[2].
• Accidental breaking changes. A renamed field breaks clients that worked yesterday, and Hyrum’s Law warns that undocumented behaviour matters too: “With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.”^[7]
• Forgotten versions. OWASP’s API9 (2023): attackers “usually get unauthorized access through old API versions or endpoints left running unpatched”^[8].
• Inconsistent, undiscoverable APIs. Postman’s 2025 survey (over 5,700 developers, architects and executives) reports 55% struggling with inconsistent documentation and 34% unable to find existing APIs; the report does not state the base^[9].

• Not an API management product. Gateways and portals are tools; API Ops is the change process around them.
• Not GitOps renamed. OpenGitOps requires pull-based, continuously reconciled state (GitOps); the decK and APIOps CLI pipelines push from CI (deck gateway sync, apiops publish)^[10][2]. Kubernetes controllers such as Tyk Operator allow a pull-based variant (tooling).
• Not API security testing, which belongs to DevSecOps; API Ops runs the cheap contract checks.
• Not integration operations. Retries, dead-letter queues and replay belong to IntegrationOps. Editorial distinction: API Ops owns the contract; IntegrationOps owns the flow.
• Not the whole APIOps Cycles operating model, which also covers strategy, platform decisions, publishing and monitoring of API capabilities^[6]; it complements this page and feeds it the first draft of a contract.
• Misconceptions: “we have a gateway, so we do API Ops” (a hand-configured gateway is the problem); “a version in the URL makes changes safe” (it only gives a breaking change somewhere to live).

• 2015: the Linux Foundation announced the Open API Initiative (5 November)^[11]; OpenAPI “was originally based on the Swagger Specification, donated by SmartBear Software”^[12].
• 2016–2018: an APIOps project for the National Library of Finland planned “APIOps Monthly Jam” sessions in 2016, and Nordic APIs describes Jarkko Moilanen as “creator of the APIOps concept”^[5]. APIOps Cycles, “Developed since 2017”^[6], was presented at the 2018 Platform Summit as a lean API design method^[13].
• 2021: Kong described APIOps as applying “the solid and proven principles of DevOps and GitOps to the API and microservice lifecycle”, one of the earliest vendor uses we found^[14].
• 2024–2025: Stripe moved to monthly non-breaking API releases from 2024-09-30.acacia^[15]; RFC 9745 standardised the Deprecation header (March 2025)^[16].
• 2026: Microsoft’s reference architecture (dated 1 September) uses a single APIOps CLI and asks users of the legacy APIOps Toolkit to migrate^[2]; the OpenAPI Initiative published Arazzo 1.1.0 (May), OpenAPI 3.2.1 and Overlay 1.2.0 (September)^[17][18][19].

Mental model: three artefacts, one loop. The contract says what the API promises; the gateway policy says how each environment exposes it; the consumer register says who depends on which version. Gates protect the register’s consumers from contract changes, the pipeline derives the policy from the contract, and telemetry keeps the register honest.

%%{init: {"flowchart": {"wrappingWidth": 150, "nodeSpacing": 18, "rankSpacing": 30, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  C["1. Contract in Git: OpenAPI or AsyncAPI"]:::core
  P{{"2. Gates: lint, breaking diff, tests"}}:::decision
  G["3. Gateway policy generated per environment"]:::core
  T["4. Telemetry per consumer and version"]:::neutral
  R["5. Consumer register: who calls what"]:::neutral
  C --> P
  P -->|"pass"| G
  P -->|"fail: fix, or add and deprecate"| C
  G --> T --> R
  R -->|"evidence for design and retirement"| C

The boundaries below are editorial distinctions made by this Atlas (coverage matrix); no standard defines them.

1. The contract is source code. Microsoft says the API definition “should be considered “source code””^[4].
2. Generate gateway configuration from the contract, as Kong’s 2021 description does^[14]; hand edits drift.
3. Fail early. “The earlier in the pipeline you can identify deviations from your standards, the faster they are to resolve.”^[14]
4. Publish your compatibility policy, then make the tools match it. A gate enforces its configuration, not your intent (contract gate).
5. One writer per target. Only the pipeline writes to production gateways, with separate identities for extracting and publishing; people need no standing write access^[2].
6. Own only what you can name. Scope each deployment to a team’s entities (tags, workspaces)^[10].
7. Retire with evidence. Deprecation is a measured migration, not an announcement.

R = responsible, A = accountable, C = consulted, I = informed. A platform team runs ruleset, pipeline and gateways as a product while owner teams own contracts (PlatformOps); with few APIs, one team owns all. A board that hand-checks every change becomes a queue: automate its rules, keep it for exceptions.

stateDiagram-v2
  [*] --> Draft
  Draft --> Beta
  Beta --> Stable
  Stable --> Deprecated
  Deprecated --> Retired
  Retired --> [*]
  Beta: Beta
  Beta: contract reviewed and mocked
  Stable: Stable
  Stable: owner, SLO, docs
  Stable: additive changes only
  Deprecated: Deprecated
  Deprecated: successor live, dates set
  Retired: Retired
  Retired: sunset passed, traffic gone

Exceptions are reviewed waiver files with an owner and expiry (oasdiff reads --err-ignore and --warn-ignore files^[28]). Escalation: a blocked breaking change goes to the API product manager, who chooses between a new version and a coordinated migration (judgement call).

A logical reference for several teams sharing a gateway platform; the shape is the same on Azure API Management or AWS.

%%{init: {"flowchart": {"wrappingWidth": 210, "nodeSpacing": 20, "rankSpacing": 30, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef risk fill:#fbeceb,stroke:#b4332b,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  K["Git, one folder per API: contract, ruleset, gateway policy, overrides"]:::core
  G{{"Pull-request gates: lint, breaking diff, conformance tests"}}:::decision
  B["Merge build: generate and lint gateway configuration"]:::core
  R["Release pipeline, sole writer: preview deletions, then sync"]:::neutral
  D["Development and staging gateways"]:::core
  P["Production gateways"]:::risk
  T["Telemetry, catalogue, consumer register"]:::neutral
  K --> G
  G -->|"pass and approve"| B
  B --> R --> D
  D -->|"approval"| P
  P --> T
  P -.->|"nightly drift check"| R
  T -.->|"evidence"| K

Trade-offs. A gateway adds “Increased response time due to the additional network hop through the API gateway”, a cost the same author calls insignificant for most applications, and another component to run^[20]. Gateway features live either in vendor extensions inside the contract (x-kong-*)^[25] or in a separate policy file (this page’s choice). And reverting an APIOps commit “doesn’t restore an incompatible or unavailable back end”^[2].

What counts as breaking is API Ops’s hardest policy call, and published policies disagree at the edges:

A dash means the source does not address the change. oasdiff’s documentation states the pattern behind most rows: narrowing what requests accept, or widening what responses return, breaks clients^[28]. Stripe puts the counterpart on consumers: “Design your integration to ignore unfamiliar fields and event types.”^[15] Write down who carries which burden, then encode it:

• Error-level findings block the merge (oasdiff breaking --fail-on ERR exits 1)^[28].
• Warnings need a named reviewer’s acknowledgement.
• Deprecation needs a date: the house Spectral rule (an Atlas rule) rejects deprecated: true without x-sunset. oasdiff blocks removing an operation or parameter before its sunset, and with --deprecation-days-stable also rejects a deprecation whose sunset is missing or too close^[28].
• Stability sets strictness: oasdiff checks beta and stable by default, not draft or alpha^[28].
• Waivers are files with owner and expiry (--err-ignore), never a disabled check.

Tool defaults are a policy too. oasdiff 1.33.0 does not read this table. It rates removing an optional response property as INFO, which oasdiff breaking never shows, and adding a response enum value as ERR, which blocks^[28]. List every check’s level with oasdiff checks changelog, then record your differences in a file passed with --severity-levels:

response-optional-property-removed    err
response-property-enum-value-added    warn

Removing a field after its sunset then needs a waiver line, which is the review you want. Zalando agrees that extending a closed enum is incompatible; where values may grow, its rule 112 lists them under examples instead^[22], so no enum finding arises.

---
config:
  sequence:
    actorMargin: 30
    width: 80
    diagramMarginX: 6
    wrap: true
    boxMargin: 6
    messageMargin: 30
---
sequenceDiagram
  autonumber
  participant Team as Team
  participant Git as Git
  participant CI as Pipeline
  participant GW as Gateways
  Team->>Git: Pull request
  Git->>CI: Run gates
  opt Break found
    CI-->>Git: Fail
    Git-->>Team: Red check
    Team->>Git: Deprecate
    Git->>CI: Re-run
  end
  CI-->>Git: Pass
  Team->>Git: Merge
  Git->>CI: Build config
  CI->>GW: Staging
  CI->>GW: Preview
  Note over Team,CI: Approver reads the planned deletions
  CI->>GW: Sync prod
  CI->>GW: Verify

Every decision leaves a record: gate results, waivers, approvals and the commit deployed to each environment. In Microsoft’s version, “The release approver reviews the resources that the dry run creates, updates, deletes, or skips”, a dry run is “a deployment gate, not a substitute for automated API tests”, and only one pipeline writes to a target at a time^[2].

Each playbook ends with an acceptance test and a rollback.

1. Start from published guidelines (Azure, Google AIPs, Zalando)^[4][36][22]. Microsoft’s own Spectral ruleset is archived because “Azure API specifications have moved to TypeSpec”^[38], so rulesets need owners.
2. Encode 10–20 rules consumers feel (naming, RFC 9457 errors^[39], pagination, security schemes, deprecation dates).
3. Extend spectral:oas; lower or switch off inherited rules with rule-name: warn or off^[40].
4. Lint the contract locally and in the pull request, and the generated gateway file with deck file lint^[25].

Acceptance: every contract lints clean; every rule says why. Rollback: introduce new rules as warn for one cycle.

1. Publish the compatibility policy and the matching levels file (contract gate).
2. In each pull request run oasdiff breaking base.yaml head.yaml --fail-on ERR --severity-levels <file>^[28].
3. Set x-stability-level per operation; require deprecated: true plus x-sunset before removal^[28].
4. Test the running service against the contract (Schemathesis)^[26]; Pact suits internal APIs with known consumers, not public APIs or pass-through gateways^[30] (see TestOps).

Acceptance: a pull request removing a response field fails; one adding an optional field passes. Rollback: warn-only with a dated issue.

Pick one scheme per API family and record it in an ADR; each has a price:

Then run deprecation as a protocol:

1. Mark the element deprecated: true with an x-sunset date in the contract^[18][28].
2. Send Deprecation (a structured date such as @1796083199) and Sunset (an HTTP date) headers and a rel="deprecation" link to the migration guide; the sunset must not precede the deprecation^[16][27].
3. Measure traffic per consumer (Lab 4) and contact each; Zalando requires usage monitoring and client approval before shut-down^[22].
4. Choose the window: GitHub keeps a previous REST version “at least 24 more months”^[37]; Meta guarantees each Graph API version at least two years of operation^[43]; Google recommends 180 days between deprecating beta functionality and removing it^[41].
5. Decide post-sunset behaviour: an error such as 410 Gone, or Meta’s forwarding to “the next oldest, usable version”^[43], which avoids outages but can change behaviour silently.

Acceptance: each deprecated element has a date, a guide and a per-consumer chart. Rollback: extend the sunset (RFC 8594 calls it a hint^[27]); never shorten it without consent.

1. Rate limits protect capacity; quotas express a plan; provider spending limits stop bill shocks (OWASP API4)^[44].
2. Size the token bucket: from full, it admits up to burst + rate × T requests in T seconds, a target, not a guarantee^[29].
3. Key limits by consumer, not IP, when clients share proxies; Kong limits by consumer by default^[45].
4. Return 429 with Retry-After^[46]; RateLimit-Policy and RateLimit headers are still an Internet-Draft (October 2026)^[47].
5. Expect approximation: AWS applies limits “on a best-effort basis”^[29]; Azure’s rate limiting “is never completely accurate” and counts per gateway^[48]. Kong’s default local policy “diverges when scaling the number of nodes”; its shared cluster and redis policies are accurate only with synchronous counter updates^[45].
6. Choose failure behaviour: Kong’s fault_tolerant defaults to true, proxying without limits while the counter store is down^[45].

Acceptance: a load test yields 429s with Retry-After at the expected rate per consumer. Rollback: change limits in Git only.

1. Keys identify; tokens authorise. AWS: “Don’t use API keys for authentication or authorization to control access to your APIs”; a key for one API in a usage plan works for every API in it^[49].
2. Validate JWT access tokens fully: typ at+jwt, exact issuer, audience naming this API, signature from the authorisation server’s keys, no alg: none, expiry^[50]. Tokens “SHOULD be audience-restricted” and minimally privileged^[51].
3. Close side doors. Kong’s OpenID Connect plugin (Enterprise) reads bearer tokens from body, header and query string by default (bearer_token_param_type); Key Auth accepts query-string keys by default (key_in_query)^[52]. Allow headers only: RFC 9700 says “Clients MUST NOT pass access tokens in a URI query parameter”, and recommends sender-constrained tokens (mutual TLS or DPoP), an option for partner APIs that IdentityOps would issue^[51].
4. Leave object-level checks to the service, which alone knows ownership (IAMOps designs scopes; DevSecOps tests authorisation).

Acceptance: tokens with wrong issuer, wrong audience, expired, or sent in a query string are refused in test. Rollback: revert the commit.

1. The pipeline is the only writer; people get read access and time-bound elevation^[2].
2. Scope every sync with --select-tag: an unscoped sync deletes whatever the file lacks; deck gateway apply never deletes and suits bootstrap only^[10].
3. Schedule deck gateway diff --non-zero-exit-code; exit code 2 means drift^[53].
4. Extract each emergency change and merge it through a pull request so Git stays authoritative^[2].

Acceptance: a deliberate manual change turns the nightly drift job red. Rollback: re-sync the last approved commit per tag.

Only the RFCs and specifications are normative, for what they cover; company guidelines are optional. None defines “APIOps”.

Selection criteria: your gateways, per-team scoping, preview of deletions, offline CI use, and OpenAPI version support across the whole chain. Not every tool lists OpenAPI 3.2 (Prism stops at 3.1^[56]), so the labs use 3.0.4. AsyncAPI: the gate chain above is OpenAPI-only; the AsyncAPI CLI’s diff classifies event-contract changes as breaking, non-breaking or unclassified^[55]. This Atlas did not test its rules: run it as a warning first and review event changes by hand.

Automate the mechanical checks (style, compatibility, conformance, drift, inventory); keep humans for domain fit, whether a break is worth a new version, and migration timing: “Tools won’t catch all problems.”^[4] AI assistants can draft descriptions or summarise a diff; their output passes the same gates. Agents are also becoming consumers: 51% of developers in Postman’s 2025 survey worry about unauthorised or excessive calls from AI agents^[9]. Per-consumer identity, quotas and telemetry make such traffic visible.

A representative design, not a recipe: an orders API on Kong Gateway 3.16, decK 1.68, OpenAPI 3.0.4 and GitHub Actions; hosts, names and dates are placeholders.

apis/orders/openapi.yaml          contract (owners: orders team)
apis/orders/catalog-info.yaml     catalogue entry that embeds the contract
apis/orders/gateway/plugins.yaml  gateway policy layered onto the generated config
.spectral.yaml                    house ruleset (owner: API platform team)
.oasdiff-levels.txt               severity levels matching the compatibility policy
.github/workflows/api-gate.yaml   pull-request gates, preview and release
ops/kong-rules.yaml               rules for generated gateway config (platform team)
CODEOWNERS                        /apis/orders/ @example/orders-team

Example status: YAML syntax-checked by the Atlas validator; not linted with Spectral or diffed with oasdiff here.

openapi: 3.0.4
info:
  title: Orders API
  version: 2.3.0
  contact: {name: Orders team, email: orders-team@example.com}
servers:
  - url: http://orders-mock:4010
paths:
  /v2/orders/{orderId}:
    get:
      operationId: getOrder
      tags: [orders]
      x-stability-level: stable
      security: [{apiKey: []}]
      parameters:
        - {name: orderId, in: path, required: true, schema: {type: string}}
      responses:
        "200":
          description: The order.
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Order"}
        "404": {$ref: "#/components/responses/Problem"}
  /v1/orders/{orderId}:
    get:
      operationId: getOrderV1
      tags: [orders]
      deprecated: true
      x-sunset: "2027-06-30"
      x-stability-level: stable
      security: [{apiKey: []}]
      parameters:
        - {name: orderId, in: path, required: true, schema: {type: string}}
      responses:
        "200":
          description: The order (legacy shape).
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Order"}
        "404": {$ref: "#/components/responses/Problem"}
components:
  securitySchemes:
    apiKey: {type: apiKey, in: header, name: apikey}
  responses:
    Problem:
      description: RFC 9457 problem details.
      content:
        application/problem+json:
          schema: {$ref: "#/components/schemas/Problem"}
  schemas:
    Order:
      type: object
      required: [id, status]
      properties:
        id: {type: string, description: Opaque identifier.}
        status:
          type: string
          description: Open set; clients must accept unknown values.
          enum: [created, paid, shipped]
        deliveryDate:
          {type: string, format: date, deprecated: true, x-sunset: "2027-06-30"}
        deliveredAt: {type: string, format: date-time}
    Problem:
      type: object
      properties:
        type: {type: string}
        title: {type: string}
        status: {type: integer}
        detail: {type: string}

The API key identifies the consumer for limits and analytics; production authorisation adds OAuth 2.0 tokens (Playbook 5).

Example status: YAML syntax-checked; rule syntax per the Spectral docs^[40]; the JSONPath filters were not executed. The ~ key selector and the numeric @property filter are documented jsonpath-plus syntax^[59], untested under Spectral.

extends: ["spectral:oas"]
rules:
  info-contact: error
  operation-id-camel-case:
    description: operationId is camelCase so generated clients read well.
    severity: error
    given: "$.paths[*][get,put,post,delete,patch].operationId"
    then:
      function: casing
      functionOptions: {type: camel}
  paths-kebab-case:
    description: Path segments are kebab-case.
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions: {match: "^(/[a-z0-9-]+|/[{][a-zA-Z]+[}])+$"}
  errors-use-problem-json:
    description: 4xx and 5xx responses use application/problem+json (RFC 9457).
    severity: error
    given: "$.paths[*][*].responses[?(@property >= 400 && @property < 600)].content"
    then:
      field: application/problem+json
      function: truthy
  deprecation-needs-sunset:
    description: Deprecated operations, parameters and properties state x-sunset.
    severity: error
    given:
      - "$.paths[*][?(@.deprecated == true)]"
      - "$.paths[*][*].parameters[?(@.deprecated == true)]"
      - "$.components.schemas[*].properties[?(@.deprecated == true)]"
    then:
      field: x-sunset
      function: truthy

Example status: YAML syntax-checked; file format from Kong’s add-plugins page^[25]; plugin fields from the Rate Limiting and Key Auth references^[45][52]; not applied to a gateway here.

add-plugins:
  - selectors:
      - $..services[*]
    overwrite: false
    plugins:
      - name: key-auth
        config:
          key_names: [apikey]
          key_in_query: false
      - name: rate-limiting
        config:
          minute: 600
          policy: redis
          redis:
            host: redis.internal.example
            port: 6379
          limit_by: consumer
          fault_tolerant: false

fault_tolerant: false returns errors instead of proxying unlimited traffic when Redis is down^[45]; choose it only if that outage is cheaper than an unprotected backend.

Example status: YAML syntax-checked; not run on GitHub. Action majors are the latest releases on 2026-10-18, all on Node 24, which runners require since Node 20’s removal on 2026-09-23^[60]; pin them by commit SHA in production. Assumes a self-hosted runner that reaches the Admin API privately and has jq; Admin API credentials are deployment-specific and omitted; the Admin API must never be reachable from the internet.

name: api-gate
on:
  pull_request:
    paths:
      - "apis/**"
      - "ops/**"
      - ".spectral.yaml"
      - ".oasdiff-levels.txt"
      - ".github/workflows/api-gate.yaml"
  push:
    branches: [main]
    paths: ["apis/**", "ops/**", ".spectral.yaml", ".github/workflows/api-gate.yaml"]
permissions:
  contents: read
jobs:
  gates:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
        with: {fetch-depth: 0}
      - uses: actions/setup-node@v7
        with: {node-version: 24}
      - uses: actions/setup-go@v7
        with: {go-version: stable}
      - name: Install pinned tools
        run: |
          npm install --global @stoplight/spectral-cli@6.17.0
          go install github.com/oasdiff/oasdiff@v1.33.0
          go install github.com/kong/deck@v1.68.0
      - name: Lint contract
        run: |
          spectral lint apis/orders/openapi.yaml --ruleset .spectral.yaml \
            --fail-severity error --format github-actions
      - name: Breaking changes against the base branch
        if: github.event_name == 'pull_request'
        run: |
          if ! git show "origin/${GITHUB_BASE_REF}:apis/orders/openapi.yaml" > base.yaml
          then
            echo "::notice::New API, no base contract: breaking diff skipped"
            exit 0
          fi
          oasdiff breaking base.yaml apis/orders/openapi.yaml --fail-on ERR \
            --severity-levels .oasdiff-levels.txt --deprecation-days-stable 180 \
            --format githubactions
      - name: Generate and lint gateway config
        run: |
          deck file openapi2kong --spec apis/orders/openapi.yaml \
            --select-tag orders-api --output-file kong.generated.yaml
          deck file add-plugins -s kong.generated.yaml \
            apis/orders/gateway/plugins.yaml > kong.plugins.yaml
          deck file add-tags -s kong.plugins.yaml orders-api > kong.yaml
          deck file lint -s kong.yaml ops/kong-rules.yaml
      - uses: actions/upload-artifact@v7
        with: {name: kong-orders, path: kong.yaml}
  preview:
    if: github.event_name == 'push'
    needs: gates
    runs-on: [self-hosted, gateway-network]
    env:
      DECK_KONG_ADDR: ${{ vars.KONG_ADMIN_URL }}
    steps:
      - uses: actions/download-artifact@v8
        with: {name: kong-orders}
      - uses: actions/setup-go@v7
        with: {go-version: stable}
      - run: go install github.com/kong/deck@v1.68.0
      - name: Plan production changes; stop above the deletion budget
        run: |
          deck gateway diff kong.yaml --select-tag orders-api --json-output > plan.json
          jq -c '.summary' plan.json >> "$GITHUB_STEP_SUMMARY"
          jq -r '.changes.deleting[] | "- delete \(.kind) \(.name)"' plan.json \
            >> "$GITHUB_STEP_SUMMARY"
          if [ "$(jq '.summary.deleting' plan.json)" -gt 3 ]; then
            echo "::error::More than 3 deletions: split the change or approve a waiver"
            exit 1
          fi
      - uses: actions/upload-artifact@v7
        with:
          name: release-orders
          path: |
            kong.yaml
            plan.json
  sync:
    needs: preview
    runs-on: [self-hosted, gateway-network]
    environment: production
    concurrency: {group: kong-production, cancel-in-progress: false}
    env:
      DECK_KONG_ADDR: ${{ vars.KONG_ADMIN_URL }}
    steps:
      - uses: actions/download-artifact@v8
        with: {name: release-orders}
      - uses: actions/setup-go@v7
        with: {go-version: stable}
      - run: go install github.com/kong/deck@v1.68.0
      - name: Sync the reviewed plan if the gateway has not changed since
        run: |
          deck gateway diff kong.yaml --select-tag orders-api --json-output > now.json
          a=$(jq -S '.changes' now.json | sha256sum | cut -d' ' -f1)
          b=$(jq -S '.changes' plan.json | sha256sum | cut -d' ' -f1)
          if [ "$a" != "$b" ]; then
            echo "::error::Gateway changed after the reviewed preview; re-run"
            exit 1
          fi
          deck gateway sync kong.yaml --select-tag orders-api

With required reviewers and self-review prevention set on the production environment, sync waits until someone other than the person who triggered the run approves^[60]; that reviewer reads the plan, deletions first, on the run’s summary page. sync stops unless the reviewed change set is unchanged — the hash covers the whole list, so a same-count swap of deletions stops the run too — and concurrency keeps one writer per target. Real estates add a staging stage and signed artefacts; ops/kong-rules.yaml can require key-auth and rate-limiting on every service. Pin tool tags you have tested^[31][32].

Environments and secrets. Keep one generated file and put only what must differ in reviewed per-environment values, as Microsoft’s override files do for “back-end URLs, resource IDs, and secret references”^[2]. decK reads a state-file value written as ${{ env "DECK_REDIS_PASSWORD" }} from the environment at sync time^[32], so the pipeline injects it from its secret store and Git holds none. The resolved value still reaches the gateway, so restrict who can read the Admin API too.

Example status: YAML syntax-checked; fields from the Backstage descriptor reference^[34]; not loaded into Backstage.

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: orders-api
spec:
  type: openapi
  lifecycle: production
  owner: orders-team
  definition:
    $text: ./openapi.yaml

$text embeds the contract file itself, so the catalogue shows the merged contract rather than a copy that can drift; move lifecycle to deprecated when the deprecation protocol starts.

Labs 1–3 were not executed here (no third-party tools were installed on the Atlas build host); Lab 4 was. Use a laptop or a disposable VM, never a shared gateway.

Objective. See style rules fail and pass. Prerequisites. Node.js 22 or 24; the contract and ruleset from the reference implementation saved as openapi.yaml and .spectral.yaml. Cost and risk. None.

npx --yes @stoplight/spectral-cli@6.17.0 lint openapi.yaml --ruleset .spectral.yaml
echo "exit code: $?"

1. Run it: expect no errors, possibly warnings from spectral:oas defaults such as missing descriptions.
2. Delete x-sunset from /v1/orders/{orderId} and run again.
3. Rename getOrder to get_order and run again.

Expected output. Step 2 reports deprecation-needs-sunset, step 3 operation-id-camel-case, each with exit code 1 (default fail severity error)^[40]. Validation. With --fail-severity warn, warnings fail the run too. Troubleshooting. Silent filter rule: test the JSONPath on a smaller file; engine error: Node too old. Teardown. Delete the folder.

Objective. Calibrate your judgement against your policy and a tool. Prerequisites. oasdiff, pinned: go install github.com/oasdiff/oasdiff@v1.33.0 — brew install oasdiff installs the latest release, and v1.34.0 (2026-10-18) changes default levels for checks this lab does not use^[31]; the two-line levels file from the contract gate saved as levels.txt. Copy openapi.yaml to base.yaml, then make these edits in head.yaml one at a time. First predict each result:

oasdiff breaking base.yaml head.yaml --fail-on ERR
echo "defaults, exit code: $?"
oasdiff breaking base.yaml head.yaml --fail-on ERR --severity-levels levels.txt
echo "policy levels, exit code: $?"

Expected output (from oasdiff 1.33.0’s rule levels, not executed here^[28]; the six rules involved are unchanged in v1.34.0’s source, checked 2026-10-19). With defaults: errors for C, D, E and F (exit code 1) and nothing for A or B, because removing an optional response property is INFO and a new response enum value is ERR. With levels.txt: errors for A, C, E and F, a warning for D (exit code 0) and nothing for B. The gap between your predictions, the defaults and the policy is the lesson. Validation. Reverted edits give no findings. Troubleshooting. Nothing for E: use an RFC 3339 sunset date^[28]; nothing at all: check both files parse (oasdiff validate). Teardown. None.

Objective. Generate Kong configuration from the contract, sync it, then detect drift. Prerequisites. Docker with Compose; decK 1.68.0; the contract from the reference implementation in ./spec/openapi.yaml. decK needs a database-backed Kong, not DB-less mode^[57]. Cost and risk. Local only; ports bound to 127.0.0.1 (Kong’s own example binds all interfaces^[61]).

Example status: YAML and bash syntax-checked; not executed. Image tags from Docker Hub on 2026-10-18; PostgreSQL 16 is in Kong 3.16’s tested range^[61].

services:
  db:
    image: postgres:16
    environment: {POSTGRES_USER: kong, POSTGRES_DB: kong, POSTGRES_PASSWORD: kong}
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "kong"]
      interval: 5s
  migrate:
    image: kong/kong-gateway:3.16.0.1
    command: kong migrations bootstrap
    environment: {KONG_DATABASE: postgres, KONG_PG_HOST: db, KONG_PG_PASSWORD: kong}
    depends_on: {db: {condition: service_healthy}}
  kong:
    image: kong/kong-gateway:3.16.0.1
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: db
      KONG_PG_PASSWORD: kong
      KONG_ADMIN_LISTEN: "0.0.0.0:8001"
    depends_on: {migrate: {condition: service_completed_successfully}}
    ports: ["127.0.0.1:8000:8000", "127.0.0.1:8001:8001"]
  orders-mock:
    image: stoplight/prism:5.15.10
    command: mock -h 0.0.0.0 /spec/openapi.yaml
    volumes: ["./spec:/spec:ro"]

docker compose up -d && sleep 20
deck gateway ping
deck file openapi2kong --spec spec/openapi.yaml --select-tag orders-api \
  --output-file kong.yaml
deck gateway diff kong.yaml --select-tag orders-api
deck gateway sync kong.yaml --select-tag orders-api
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8000/v2/orders/42
curl -s -o /dev/null -w "%{http_code}\n" -H "apikey: lab-key" \
  http://127.0.0.1:8000/v2/orders/42
# Drift: change a route by hand, then ask decK what differs (exit code 2 = drift).
deck gateway diff kong.yaml --select-tag orders-api --non-zero-exit-code
echo "diff exit code: $?"

Expected output. The first diff lists entities to create. After sync, the first curl prints 401: the Prism mock, which builds responses from the contract, fails requests whose declared security information is missing^[56]. With any apikey header it prints 200 (this lab adds no Key Auth plugin, so Kong does not check the key). Validation. Change a route’s paths through the Admin API: the final diff exits 2^[53] and sync restores it. Troubleshooting. 405 from the Admin API: DB-less mode; connection refused: KONG_ADMIN_LISTEN or port bindings. Teardown. docker compose down -v removes containers and the database volume.

Objective. Compute this page’s SLIs and deprecation evidence from gateway logs. Prerequisites. Python 3.8 or later; a JSON Lines extract with consumer, version, status, latencies and who produced the status. Cost and risk. Read-only; strip client IPs and tokens first.

Example status: executed on 2026-10-18 with Python 3.8.10 against a 20-line synthetic log written for this lab (revision r1); not run on real gateway logs. Percentiles checked by hand.

#!/usr/bin/env python3
"""API KPIs from gateway access logs in JSON Lines (standard library only).

Usage: python3 api_kpis.py access.jsonl [threshold_ms] [deprecated_versions]
One request per line, for example:
{"consumer": "acme-mobile", "version": "v2", "route": "GET /orders/{id}",
 "status": 200, "latency_ms": 120, "upstream_ms": 105, "source": "upstream"}
"source" names who produced the status: "gateway" (auth, limits) or "upstream".
"""
import json
import math
import sys
from collections import Counter


def p95(values):
    """Nearest-rank 95th percentile (no interpolation)."""
    ordered = sorted(values)
    return ordered[math.ceil(0.95 * len(ordered)) - 1]


def load(path):
    with open(path, encoding="utf-8") as handle:
        return [json.loads(line) for line in handle if line.strip()]


def main():
    rows = load(sys.argv[1])
    threshold = float(sys.argv[2]) if len(sys.argv) > 2 else 300.0
    deprecated = set((sys.argv[3] if len(sys.argv) > 3 else "v1").split(","))
    total = len(rows)
    if not total:
        sys.exit("no requests in the log")
    bad = sum(1 for r in rows if r["status"] >= 500)
    throttled = Counter(r["consumer"] for r in rows if r["status"] == 429)
    by_consumer = Counter(r["consumer"] for r in rows)
    rejected = sum(1 for r in rows if r["source"] == "gateway")
    # Latency only for proxied calls: fast gateway rejections would flatter it.
    proxied = [r for r in rows if r["source"] == "upstream"]
    old = Counter(r["consumer"] for r in rows if r["version"] in deprecated)

    print(f"requests                  {total}")
    print(f"availability SLI          {(total - bad) / total:.2%}  (5xx count as bad)")
    if proxied:
        fast = sum(1 for r in proxied if r["latency_ms"] <= threshold)
        overhead = [r["latency_ms"] - r["upstream_ms"] for r in proxied]
        print(f"latency SLI (<= {threshold:.0f} ms)   {fast / len(proxied):.2%}"
              f"  ({len(proxied)} proxied)")
        print(f"p95 latency               {p95([r['latency_ms'] for r in proxied])} ms")
        print(f"p95 gateway overhead      {p95(overhead)} ms")
    print(f"rejected at the gateway   {rejected / total:.2%} (auth, limits)")
    print(f"throttled (429)           {sum(throttled.values()) / total:.2%}")
    for consumer, count in throttled.most_common():
        share = count / by_consumer[consumer]
        print(f"  {consumer}: {count} of {by_consumer[consumer]} ({share:.0%})")
    print(f"deprecated-version share  {sum(old.values()) / total:.2%}")
    for consumer, count in old.most_common():
        print(f"  still calling {'/'.join(sorted(deprecated))}: {consumer} ({count})")


if __name__ == "__main__":
    main()

Run python3 -I api_kpis.py access.jsonl 300 v1. Actual output on the synthetic log (20 requests; 2 server errors; 2 throttled and 1 unauthenticated request rejected by the gateway; 5 requests on v1):

requests                  20
availability SLI          90.00%  (5xx count as bad)
latency SLI (<= 300 ms)   82.35%  (17 proxied)
p95 latency               520 ms
p95 gateway overhead      20 ms
rejected at the gateway   15.00% (auth, limits)
throttled (429)           10.00%
  partner-shipco: 2 of 5 (40%)
deprecated-version share  25.00%
  still calling v1: legacy-erp (4)
  still calling v1: acme-mobile (1)

Validation. By hand: 18 of 20 requests are not 5xx (90%); 14 of 17 proxied requests take 300 ms or less (82.35%), while counting the three fast rejections would have reported 85%. Interpretation. The availability SLI counts 429s as good, like Google’s worked example^[62], yet one partner lost 40% of its calls: report rejections per consumer beside it. Troubleshooting. KeyError: map your gateway’s field names. Teardown. Delete the log extract.

The first four are documented by the providers; the measures are this Atlas’s suggestions.

Worked calculation (illustrative month). An API serves 48,600,000 requests; 31,590 are 5xx. Availability = 1 − 31,590 ÷ 48,600,000 = 99.935%. Against a 99.9% SLO the month allows 48,600 bad requests, so 65% of the error budget is spent (see SRE for budget policy). 291,600 requests (0.6%) were throttled, but one partner had 18% of its calls throttled: a wrong limit or a client retrying without backoff. Version v1 carried 1,652,400 requests (3.4%) from seven consumers, 71% from one, so one conversation decides the sunset. Over the quarter, 140 contract changes merged and 2 caused consumer incidents: escape rate 1.4%; the gate blocked 23, so catch rate = 23 ÷ 25 = 92%.

Review the first three weekly, the rest monthly; set targets after a baseline quarter. SLO or SLA? An SLO is your internal target; an SLA is “an explicit or implicit contract with your users that includes consequences of meeting (or missing) the SLOs they contain”^[65]. Promise partners an SLA looser than the SLO you meet, measured the same way, and never present rate limits, which AWS calls targets, as guaranteed throughput.

• Inventory first: every exposed host and version with owner and data sensitivity; “Include the documentation build in your CI/CD pipeline”; protect old versions or retire them^[8].
• Resource limits on payload size, page size, execution time and paid downstream calls (API4)^[44].
• Credentials: keys identify, tokens authorise (Playbook 5); keep secrets out of contracts and generated files, and inspect extracted artefacts for them^[2].
• The control plane is production: admin interfaces on a private network (decK passes credentials with --headers^[32]); separate least-privilege identities for extracting and publishing; workload identity where available^[2].
• Privacy: synthetic data in examples and mocks; set retention and access for gateway logs, which hold consumer identifiers and IP addresses.
• Compliance evidence: commit, approval, gate results and deployed commit form a change record auditors can sample; whether it satisfies a framework is for your compliance function (ComplianceOps).

• Gateway and pipeline costs depend on tier, units, regions and usage; Microsoft gives no fixed estimate^[2]. AWS charges extra for per-method metrics^[35].
• Limits are not budgets. AWS: “Don’t rely on usage plan quotas or throttling to control costs or block access to an API.”^[49] Use billing alerts and provider spending limits^[44].
• Capacity arithmetic. Rate 50 per second, burst 100: the token-bucket bound for one minute from a full bucket is 100 + 50 × 60 = 3,100 requests, which AWS treats as a target, not a ceiling^[29]. With Kong’s per-node local counters^[45], a 600-a-minute consumer behind four round-robin nodes can get up to 4 × 600 = 2,400 (illustrative).
• Version sprawl is the hidden cost: “Running multiple versions of an API requires additional management resources”^[8]; retiring versions is also the sustainability lever.

Healthy signals: zero drift findings; no human writes to production gateways except recorded emergencies; inventory coverage near 100%; no expired waivers; each deprecated version dated with falling per-consumer traffic. Monthly, trace one merged change from pull request to deployed configuration.

%%{init: {"flowchart": {"wrappingWidth": 160, "nodeSpacing": 16, "rankSpacing": 26, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef risk fill:#fbeceb,stroke:#b4332b,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  A["404 spike on paths owned by another team, minutes after a release"]:::risk
  B["Freeze: pause all gateway pipelines"]:::core
  C{{"Did the release log or diff report deletions?"}}:::decision
  D["Re-sync each affected team's last approved commit with its own tag"]:::core
  E["Look elsewhere: backend or DNS change, expired certificate"]:::core
  F["Verify: drift diff clean for every tag; 404 rate back to baseline"]:::core
  G["Prevent: mandatory select tags; owner-tag lint; deletion budget in the preview"]:::core
  A --> B --> C
  C -->|"yes"| D --> F --> G
  C -->|"no"| E

Worked runbook (illustrative). 14:02, the payments release ran deck gateway sync payments.yaml without --select-tag; decK deleted the orders and catalog routes, which were not in the file^[10]. 14:06, the 404 alert fires.

1. Contain (5 minutes). Pause every gateway pipeline; name an incident owner.
2. Confirm. The release log lists deletions; deck gateway diff orders.yaml --select-tag orders-api from the orders team’s last approved commit lists entities to create^[53].
3. Recover. Sync each affected team’s last approved artefact with its own tag, not by hand in the Admin API (new drift).
4. Verify. Clean drift diff for every tag; 404 and 5xx rates at baseline; smoke tests pass.
5. Prevent. Mandatory --select-tag in the shared release template, an owner-tag lint rule, and the preview job’s deletion budget (release workflow).
6. Review. Blameless review with owned actions (IncidentOps).

• Portal-first, export later: the contract documents the past. Git first; extract only to bootstrap.
• Contract as documentation only: if no gate reads it, it drifts.
• The 200-rule ruleset: hundreds of warnings teach people to ignore them. Few rules, each with a reason.
• A major version per change: /v7/ means six sets of tests and docs. Prefer additive change and deprecation.
• Deprecation by email: without headers, dates and per-consumer traffic, sunsets slip forever.
• Business logic in the gateway: transformations hide behaviour outside the contract and the service’s tests.
• Quotas as budgets, keys as authentication (AWS warns against both^[49]).
• Myth: design-first is waterfall. A contract can be written in an hour, mocked, and changed many times before code exists.
• Myth: GraphQL needs no governance. It avoids versions^[42] but still needs deprecation, usage tracking and limits.

Use it when several teams share gateways, when consumers you do not control (partners, customers, mobile apps) depend on your contracts, when changes are frequent, or when you must show who approved each production change. Microsoft frames the decision around ownership, review requirements and deployment boundaries, which “don’t have fixed thresholds”^[2].

Do not build the full pipeline for one internal API with two known consumers that changes twice a year: a contract in Git, a linter and a reviewed pull request suffice; Microsoft advises small, slow-changing estates to “begin with a manual pull request workflow”^[2]. Skip gateway-as-code without a gateway, and breaking gates for drafts nobody calls. If infrastructure and API configuration always change together, one IaC pipeline may serve both^[2]. Hidden responsibility: someone owns the ruleset, levels file, waivers and consumer register indefinitely.

%%{init: {"flowchart": {"wrappingWidth": 150, "nodeSpacing": 16, "rankSpacing": 26, "padding": 8}}}%%
flowchart TB
  classDef core fill:#e8f3f2,stroke:#16756f,color:#122029
  classDef decision fill:#fdf3e3,stroke:#c9800f,color:#122029
  classDef neutral fill:#f1f4f6,stroke:#5b7a87,color:#122029
  Q1{{"Do consumers outside the owning team depend on the API?"}}:::decision
  N1["Contract in Git plus lint in CI; revisit yearly"]:::neutral
  QG{{"Is there an API gateway in front of it?"}}:::decision
  Q2{{"External consumers, several teams on one gateway, or weekly changes?"}}:::decision
  L2["Breaking-change gate, deprecation dates, per-consumer telemetry"]:::core
  L3["Full pipeline: generated config, scoped sync, drift checks, sole writer"]:::core
  Q1 -->|"no"| N1
  Q1 -->|"yes"| QG
  QG -->|"no"| L2
  QG -->|"yes"| Q2
  Q2 -->|"no"| L2
  Q2 -->|"yes"| L3

This is this Atlas’s model, not an industry standard.

Preflight for a new API

• Contract in Git, design reviewed, linted clean
• Versioning scheme and compatibility policy referenced
• Owner, consumers, stability level and SLO recorded
• Error format RFC 9457; size and page limits set
• Authentication scheme, scopes and rate limits reviewed

Pull-request review

• Gates green; any waiver has an owner and expiry
• Warnings acknowledged by a named reviewer
• Deprecations carry a sunset date and migration note
• Gateway policy diff read, especially deletions

Deprecation and sunset

• Successor live and documented
• Deprecation and Sunset headers configured; rel="deprecation" link
• Every remaining consumer identified and contacted
• Post-sunset behaviour (error or forwarding) tested

Quarterly audit

• Inventory reconciled: gateway, contracts, catalogue
• Drift findings and manual-write audit reviewed
• Ruleset and tool versions reviewed; expired waivers removed

Pull-request template for an API change

API: <name>            Stability: draft | beta | stable
Change type: additive | deprecating | breaking (needs version + approval)
Consumers affected: <list or "none known"> Evidence: <dashboard link>
Gate results: lint <pass/fail>  breaking diff <none/WARN/ERR>  tests <pass/fail>
Waivers: <file, owner, expiry> or none
Gateway policy changes: <limits, auth, routes; deletions?>
Rollback: <revert commit; backend compatibility checked? yes/no>

Deprecation notice

Subject: <API> <version or operation> deprecated on <date>, sunset on <date>
What changes: <element> is replaced by <successor>. Migration guide: <link>
Why: <one sentence>
Your traffic: <consumer> made <n> calls to the deprecated element in the last 30 days
Signals: responses carry Deprecation and Sunset headers from <date>
After sunset: requests return <status> | are forwarded to <version>
Contact: <team channel>; request an extension before <date>

Architecture decision record: versioning scheme

Context: consumers (internal/partner/public), change rate, gateway capabilities
Options: URL major version | dated header | media type | versionless + deprecation
Decision: <option>; compatibility policy: <link>
Support window: previous version kept <n> months after successor release
Consequences: maintained shapes, test matrix, routing rules, docs
Review date: <date>

API scorecard (monthly, per API)

Availability SLI ......  99.__ %   Latency SLI ....... __ %
Gateway rejections ....  __ %      worst consumer: <name> __ %
Contract drift ........  __ entities   Inventory coverage __ %
Breaking escapes ......  __ this quarter   Waivers open: __ (oldest __ days)
Deprecated traffic ....  __ % from __ consumers   next sunset: <date>

Do we need a gateway to practise API Ops? No. Contracts in Git, linting and breaking-change gates help any API. Gateway-as-code applies only where a gateway exists.

We have hundreds of APIs and no contracts. Where do we start? Extract what the gateways know (Microsoft’s extract-first path^[2]), commit it as a reviewed baseline, gate only new changes, and add real contracts as each API next changes.

Does this apply to GraphQL or gRPC? Yes, with other tools. GraphQL evolves a versionless schema^[42]; Google’s AIP-180 states its compatibility rules in Protocol Buffers terms (fields, messages, oneofs)^[36]. Gates, scoped deployment and drift checks stay the same.

Where should the contract live: with the code or in a central repository? With the code when one team owns both and releases them together; central (or mirrored) when a platform team must lint and gate all APIs. Either way, one file is the source of truth.

Is this just GitOps? It borrows Git as source of truth and drift detection, but the decK and APIOps CLI pipelines push rather than reconcile continuously; Kubernetes controllers such as Tyk Operator allow the pull model (GitOps explains it).

• Established now: OpenAPI 3.2 adds a query operation for the HTTP QUERY method and streaming media types^[18]; Overlay 1.2.0 yields audience- or gateway-specific variants from one contract^[19].
• Maturing: Arazzo 1.1.0 describes multi-call workflows for tests and documentation^[17]; RateLimit headers are still a draft^[47].
• Early: AI agents as consumers^[9] and contract-aware review assistants; treat vendor claims as marketing until tested.
• Kubernetes: Gateway API (Gateway, HTTPRoute) is “focused on L4 and L7 routing”^[66]; quotas, keys and portals come from your gateway product.

Situation (illustrative). Orders v1 has 30 consumers (24 internal, 6 partners). Its decimal amount in major currency units causes rounding disputes; the fix is an integer amount in minor units plus a currency code. Engineers want 12 other clean-ups too. Option A: launch v2 with all 13 changes; sunset v1 in 18 months. Option B: add amountMinor and currency to v1 (additive, so the gate passes), deprecate amount with a 12-month sunset, and migrate consumer by consumer.

Assumptions. Three internal consumers carry 70% of traffic; partners carry 20% and release quarterly; consumers ignore unknown fields, as Stripe asks of its integrators^[15] (verify with tests).

Why the attractive choice can be wrong. Option A looks clean but asks 30 consumers to absorb 13 changes for one fix. Quarterly partners slip, v1 outlives its sunset, and the team runs two full versions, the sprawl that costs “additional management resources”^[8]. Option B asks each consumer to change one field and turns migration into a per-consumer chart.

Recommendation. Option B, unless the resource model itself must change (then a new version is honest); bundle clean-ups only when consumers must migrate anyway. Uncertainty: typed partner SDKs may need a release to read the new field, and a partner that cannot move in 12 months forces an extension.

You should now be able to explain what APIOps means and why it is unstandardised; write a compatibility policy and make the tools enforce it; design a pipeline that generates and scopes gateway configuration; measure rejections and deprecated traffic per consumer; and decide between a new version and an additive migration.

1. A manager says: “We run Kong, so we do APIOps.” What would you check?

2. Under this page’s gate defaults, which block: (a) a new optional parameter, (b) an optional parameter made required, (c) a new response enum value, (d) a smaller default page size?

3. A shared Kong gateway is updated by deck gateway sync team.yaml from five repositories. What is the risk and the fix?

4. The API-wide 429 rate is 0.6%, but one partner sees 18%. Name two likely causes and the next step.

5. A colleague proposes AWS usage-plan API keys as the access control for a partner API. Your answer?

6. A team sets Deprecation: @1798761600 (1 January 2027) and Sunset: Tue, 01 Dec 2026 00:00:00 GMT. What is wrong?

API Ops has no standard and no governing body; it is a vendor-popularised name for an idea that holds up anyway: an API is a promise, and promises need a change process. Put the contract in Git, decide in writing what counts as breaking, let a pipeline that nobody bypasses generate and scope gateway configuration, and retire versions with evidence about who still depends on them. The checks run on open-source tools; the hard part is the policy, and that is where this page asks you to spend your effort.

All sources were opened on 2026-10-18; dates are the sources’ own. Claim-level notes and gaps are in research/api-ops-ledger.md.

Changelog. 2026-10-18, r0: first draft (research, ledger, six diagrams). 2026-10-18, r1: after independent review reviews/api-ops-r1.md: oasdiff levels file and corrected Lab 2; preview, deletion budget, approval and concurrency in the release; pull-based operators; both meanings and 2016–2018 history of “APIOps”; AIP-180 cells; current action majors; Lab 4 latency over proxied calls (re-executed); portal, SLA, AsyncAPI and secrets notes; glossary; Figures 2, 4 and 6 redrawn. 2026-10-19, post-score polish after reviews/api-ops-score.md (F1–F5): Meta guarantee reworded as a paraphrase (the page’s two guarantee sentences are recorded in the ledger); the Spectral ruleset status line names the untested jsonpath-plus constructs; Lab 2 pins oasdiff instead of brew install and records that the six rules it uses are unchanged at v1.34.0; the release re-diff guard hashes the change list instead of comparing summary counts; the Node 20 footnote date is explained.