api-spec-openapi

OpenAPI 3.1 + Zalando REST API Guidelines Skill

When to Activate

• Authoring a new OpenAPI 3.1 specification from domain models
• Updating an existing OpenAPI spec to align with Zalando conventions
• Reviewing specs for API naming, error handling, pagination, versioning, or idempotency compliance
• Preparing specs for publication to SmartBear SwaggerHub
• Designing API contracts for a bounded context or microservice

Core Rules Digest (Zalando-Derived)

The highest-value Zalando rules are embedded below. Full checklist with verifiable YAML snippets: zalando-checklist.md.

Naming

• Paths: kebab-case, lowercase, plural resource nouns, no trailing slash.

  /v1/users
  /v1/market-searches/{id}
  /v1/order-items
  

• JSON properties: snake_case (not camelCase).

  user_id: string
  created_at: string
  is_active: boolean
  

• Identifiers MUST be English — all path segments, property names, enum values, operationIds, and schema names MUST be English (e.g., /customers/{id}/invoices, not /clients/{id}/factures). See zalando-checklist.md § English-only identifiers.

HTTP Semantics

• GET: retrieve (200 OK or 404).
• POST: create new resource (201 Created, Location header with URI).
• PUT: replace entire resource, idempotent (200 or 204).
• DELETE: remove resource, idempotent (204 No Content).
• PATCH: partial update (not recommended; use PUT or POST instead).
• Status codes: Use 200/201/202/204/207/400/401/403/404/409/412/422/429/500. See zalando-checklist.md § HTTP Status Codes for mappings.

Pagination (Cursor-Based, No Offset)

• Cursor pagination: ?cursor=<opaque-value>&limit=<int> (default limit 20, max 100).
• Forbid ?offset= and ?page= — they are inefficient at scale.
• Response envelope includes _links.next / _links.prev for navigation.

  items: [...]
  _links:
    next: { href: "https://api.example.com/v1/users?cursor=abc123&limit=20" }
    prev: { href: "https://api.example.com/v1/users?cursor=xyz789&limit=20" }