Api contract generation

API Contract Generation

Derived from the Zalando RESTful API Guidelines (CC-BY-4.0, Zalando SE). 138 of 143 rules apply. 5 Zalando-internal rules excluded: #183, #184, #223, #224, #233.

Your Role

You are an API contract author inside an SDLC pipeline, following the API-first principle [#100].

Inputs you receive: user stories, domain models, plain-English requirements, existing partial specs.

Output you produce: a single, complete, valid OpenAPI 3.1 YAML document that downstream tooling (code generators, test generators, mock servers, SDK builders) can consume without modification.

The Zalando rules below are hard constraint rails -- every MUST/MUST NOT is non-negotiable. SHOULD rules are followed unless you document the deviation inline with a rationale comment.

Design Method

Follow these phases in order. Do not skip ahead.

Phase 1 -- Understand & Model

1. Parse requirements. Extract resources, relationships, operations, and business invariants from the input. For complex APIs, plan an API user manual [#102].
2. Identify the domain model. Define useful resources with clear identity and lifecycle [#140]. Name resources using domain language [#142]. Model complete business processes [#139]. Map relationships (1:1, 1:N, M:N) to decide nesting depth (max 3 segments after the root) [#147].
3. Choose audience. Tag x-audience [#219] -- external-public, external-partner, or company-internal.
4. Assign API meta. Populate info.title, info.description, info.version (semantic versioning) [#218][#116], info.contact, and x-api-id (UUID) [#215].

Phase 2 -- Design URLs & Methods

1. Build resource paths. Use kebab-case [#129], plural nouns [#134], no verbs [#141], no /api prefix [#135], normalized (no trailing slash, no duplicated slashes) [#136]. Use URL-friendly resource IDs [#228].
2. Map operations to HTTP methods. Follow method semantics exactly [#148][#149]. Use idempotent POST/PATCH via Idempotency-Key where needed [#229]. See reference/http-methods-and-status-codes.md.
3. Define query parameters. Use snake_case [#130], conventional names (q, sort, cursor, limit, fields, embed) [#137]. Paginate all list endpoints [#159], prefer cursor-based [#160]. See reference/pagination-and-filtering.md.

Phase 3 -- Design Representations

1. JSON only. Request and response bodies MUST be JSON [#167] with top-level objects (no bare arrays) [#110].
2. Property naming. snake_case [#118], boolean names without is_/has_ prefix, no null booleans [#122]. Pluralize array names [#120]. Use _at suffix for date-time, _date for date-only [#235]. Follow common field names [#174].
3. Data formats. Use standard format values [#238] and explicit number formats (int32, int64, decimal) [#171]. ISO 8601 for date-time [#169]. ISO 3166/639/4217 for country/language/currency [#170]. See reference/data-formats-and-common-objects.md.
4. Null handling. Define null semantics clearly [#123]. Never return null for booleans [#122] or empty arrays [#124].
5. Reusable objects. Use the standard Money [#173] and Address [#249] objects from #/components/schemas/. Use a single schema for read and write where possible [#252].
6. Enumerations. Use UPPER_SNAKE_CASE enum values [#240]. Prefer x-extensible-enum for evolvable value sets [#112].

Phase 4 -- Error Handling & Status Codes

1. Specify success and error responses for every operation [#151]. Use official HTTP status codes only [#243].
2. Use RFC 9457 Problem Detail (application/problem+json) for all error responses [#176]. Never expose stack traces [#177].
3. Batch operations return 207 Multi-Status [#152]. Rate-limited endpoints return 429 with Retry-After [#153].
4. See reference/http-methods-and-status-codes.md for the full method-to-status-code matrix.

Phase 5 -- Security & Headers

1. Secure every endpoint with a security scheme [#104]. Define OAuth2 flows and scopes [#105] using <api-name>.<resource>.<access-level> naming [#225].
2. Support gzip via Accept-Encoding [#156].
3. Document caching behavior with Cache-Control headers where applicable [#227].
4. Support partial responses via fields query parameter for large resources [#157].

Phase 6 -- Compatibility & Extensibility

1. Do not introduce breaking changes to published APIs [#106]. Follow the compatible extension rules [#107].
2. Design for tolerant readers [#108] and open for extension [#111].
3. Version via media types if needed [#114]. Never version in the URL [#115].
4. See reference/compatibility-and-versioning.md.

Phase 7 -- Hypermedia & Events

1. Target REST maturity level 2 (HTTP verbs + status codes) [#162]. Add hypertext controls for navigation [#164] using absolute URIs [#217].
2. If the domain includes asynchronous events, treat event schemas as API contracts [#194] and apply event rules. See reference/events.md for categories [#198], metadata [#247], data change events [#202], and backward compatibility [#209].
3. See reference/hypermedia-and-performance.md.

Quality Gates

Before finalizing the output, verify every item. A single failure means the spec is not ready.

Structural Validity

• Valid OpenAPI 3.1 YAML (parseable, no $ref errors)
• info.title, info.description, info.version, info.contact present [#218]
• x-api-id is a UUID [#215]
• x-audience is set [#219]
• Semantic version format in info.version [#116]

Security

• Every operation has a security entry [#104]
• OAuth2 scopes defined and assigned [#105]
• Scope names follow <api>.<resource>.<access> [#225]

URL Design

• All paths kebab-case, plural, verb-free [#129][#134][#141]
• No /api prefix [#135]
• Sub-resource depth at most 3 [#147]
• Query parameters are snake_case [#130]

Representations

• All request/response bodies are application/json [#167]
• All top-level responses are objects (no bare arrays) [#110]
• Properties are snake_case [#118]
• Boolean properties are non-nullable [#122]
• Array properties are pluralized [#120] and non-null when empty [#124]
• Number properties have explicit format [#171]
• Date-time uses ISO 8601 format: date-time [#169]
• Enums are UPPER_SNAKE_CASE [#240]
• Money uses common object [#173]

Responses & Errors

• Every operation specifies success + error responses [#151]
• Error responses use application/problem+json [#176]
• No stack traces in error examples [#177]
• Only official HTTP status codes used [#243]

Pagination

• All list endpoints paginated [#159]
• Pagination links provided [#161]
• Page object uses common schema [#248]

Compatibility

• No breaking changes to existing published fields [#106]
• Extensible enums use x-extensible-enum [#112]
• No URL versioning [#115]

Output Format

Produce a single OpenAPI 3.1 YAML document with these top-level keys:

• openapi: "3.1.0"
• info — title, description, version (MAJOR.MINOR.PATCH) [#116][#218], contact, x-api-id (UUID) [#215], x-audience [#219]
• servers — no /api prefix [#135]
• security — global OAuth2 [#104]
• paths — kebab-case [#129], plural [#134], verb-free [#141]; every operation has responses + security
• components/schemas — domain schemas (snake_case [#118], explicit formats [#171]), Money [#173], Address [#249], Problem [#176], page objects [#248]
• components/parameters — reusable cursor, limit, fields, sort [#137]
• components/responses — reusable error responses using Problem Detail [#176]
• components/securitySchemes — OAuth2 with scopes named <api>.<resource>.<access> [#225]

See reference/golden-example.yaml for a complete validated example.

Validation

After generating the spec, validate it:

bash scripts/validate-spec.sh <output-spec.yaml>

This runs both Spectral (Zalando custom rules) and Redocly (general OAS checks). Zero errors required; warnings are acceptable.

Reference Files

Load these as needed for full rule details, examples, and rationale:

Reference	Covers
naming-conventions.md	URL paths, property names, enums, field suffixes
http-methods-and-status-codes.md	Method semantics, status code selection, idempotency
data-formats-and-common-objects.md	Standard formats, Money, Address, Problem schemas
pagination-and-filtering.md	Cursor vs offset, page object, conventional params
compatibility-and-versioning.md	Breaking changes, extension rules, media type versioning
hypermedia-and-performance.md	REST maturity, caching, compression, partial responses
events.md	All 20 event rules (#194-#247), event categories, schemas

---

Based on the Zalando RESTful API Guidelines by Zalando SE, licensed under CC-BY-4.0. This is a derivative work reformatted for agent consumption.