Skip to content

Spec API Lifecycle and Governance

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: API Lifecycle and Governance

Part of the Technical Specification. Requirement prefix: LCY. Draws on the Microsoft REST API Guidelines, Google API Improvement Proposals (AIPs) and the Zalando RESTful API Guidelines, adapted to this specification.

1. Lifecycle

flowchart LR
  I[Idea: a client question] --> D[Design: OpenAPI draft and examples]
  D --> R[Design review]
  R --> B[Build behind a flag]
  B --> BE[Beta: opt-in keys]
  BE --> GA[Stable]
  GA --> DE[Deprecated]
  DE --> SU[Sunset]
Loading

2. Design-first

The project has decided that the published OpenAPI document is generated from the code (API Design). Design-first is kept by reviewing the interface before the implementation:

ID Requirement Verification
LCY-001 Every new or changed operation MUST start with a design pull request containing the OpenAPI fragment (paths, parameters, schemas, examples, problem types) and the requirement rows on the relevant spec page, reviewed and approved before implementation starts. Review
LCY-002 The generated document MUST match the approved fragment; a difference fails CI until the design is re-approved. Lint
LCY-003 Every operation MUST pass through beta (VER-007) unless the owner waives it for a minor, additive change. Review

3. Style guide (summary)

Topic Rule Reference
Resource names plural nouns, kebab-case paths, no verbs except composed features named as outcomes (route-briefing) PROT-005
Parameters snake_case, units in names, comma-separated lists CONV-002, CONV-006
Payload members camelCase, units in names, no abbreviations except id, km, kw CONV-002
Types instants in UTC with Local companions, money as decimal strings, WGS 84 CONV-003 to CONV-008
Enumerations open, snake_case, documented ENV-050
Collections always wrapped in the envelope, cursor paging, stable order ENV-020 to ENV-026
Errors RFC 9457 with the catalogue ERR
Booleans named as positive facts (availableNow, not notAvailable)
Nullability explicit; no tri-state booleans ENV-040, CONV-012
Ids opaque, prefixed CONV-010

4. Lint ruleset for the OpenAPI document

The ruleset is a Spectral-compatible ruleset (the tool may change with the stack; the rules do not). Every rule is an error unless marked warn.

Rule Checks
vf-operation-id every operation has a unique lowerCamelCase operationId
vf-operation-docs summary, description, at least one example per response, tag
vf-x-extensions x-scope, x-source-families, x-cache-family, x-stability present; x-mcp-counterpart where one exists
vf-path-case lower-case kebab-case segments, plural collections, no trailing slash
vf-param-case query parameters snake_case; no parameter named key, api_key, token
vf-member-case schema properties camelCase
vf-units numeric properties with a unit carry a unit suffix
vf-instant-local a human-facing date-time property has a …Local sibling (allow-list for technical instants)
vf-money no number for properties named like prices; Money schema used
vf-envelope every 200 JSON schema requires data, meta, links
vf-problem every 4xx/5xx uses application/problem+json and the Problem schema
vf-no-409 no 409 response
vf-429-retry-after every 429 and 503 declares Retry-After
vf-security every non-service operation requires a security scheme
vf-extensible-enum every enum in a response has x-extensible-enum: true
vf-pagination list operations declare limit and cursor with bounds
vf-no-storage-names no name matches the hashed denylist of storage names
vf-no-collection-vocabulary descriptions contain no collection vocabulary (allow-list reviewed)
vf-bounded-strings (warn) strings in parameters have maxLength

5. Governance

ID Requirement Verification
LCY-010 The ruleset MUST run on every pull request and fail on any error rule. Lint
LCY-011 The owner is the API's product owner; changes to conventions on this page need the owner's approval and an ADR. Review
LCY-012 Each operation MUST have an owner recorded in the code-owners file. Ops
LCY-013 An inventory of every operation with its stability, version and deprecation dates MUST be published with the documentation (OWASP API9). Docs
LCY-014 Deprecation MUST follow VER-003 and VER-008; an operation MUST NOT be removed without a sunset period. Contract

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally