Repository navigation
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.
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]
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 |
| 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 |
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
|
| 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 |
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference