api-spec-openapi

Files (6)

• SKILL.md
• bounded-context-mapping.md
• openapi-3.1-template.md
• problem-json.md
• validation.md
• zalando-checklist.md

SKILL.md (first lines)

# 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](zalando-checklist.md).

### **Naming**
- Paths: **kebab-case**, lowercase, **plural resource nouns**, no trailing slash.
  ```yaml
  /v1/users
  /v1/market-searches/{id}
  /v1/order-items
  ```
- JSON properties: **snake_case** (not camelCase).
  ```yaml
  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](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](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.
  ```yaml
  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" }
  ```

### **Errors: RFC 9457 Problem+JSON**
- All 4xx/5xx responses use `application/problem+json` (RFC 9457 / RFC 7807).
- Single reusable `Problem` schema across all endpoints.
  ```yaml
  type: string        # URI identifying problem type (e.g., "https://api.example.com/problems/user-not-found")
  title: string       # Human-readable summary
  status: integer     # HTTP status code
  detail: string      # Details specific to this occurrence
  instance: string    # URI to affected resource
  ```

### **Versioning (URL Major Only)**
- Major versions encoded in URL: `/v1/`, `/v2/`.
- **Preferred within-version evolution**: Additive only (no breaking changes within `/v1`).
- Alternative: Media-type versioning (content negotiation `Accept: application/vnd.example.v1+json`); see [openapi-3.1-template.md](openapi-3.1-template.md).
- **MUST NOT break** existing clients mid-version; bump major version if backward-incompatible.

### **Idempotency**
- **POST (create)**: Require `Idempotency-Key` header (UUID or user-provided).
- **PUT / DELETE**: Inherently idempotent; safe to retry.
- Server returns same response if the same `Idempotency-Key` is submitted.

### **Filtering & Sorting**
- Filtering: Query parameters per resource (`?user_id=123`, `?status=active`).
- Searching: `?q=<query>` for free-text search.
- Sorting: `?sort=field,-field` (ascending by default, `-` prefix for descending).

### **Hypermedia & Links**
- Include `_links` object in responses for navigation (cursor pagination, related resources, actions).
- Standard link relations: `self`, `next`, `prev`, `first`, `last`.

### **Headers & Content Types**
- Default: `application/json`.
- Errors: `application/problem+json`.
- Concurrency: `ETag` / `If-Match` for optimistic locking.
- Retry: `Retry-After` on 429 (rate limit) and 503 (service unavailable).

### **Deprecation**
- Use `Deprecation: true` header in responses.
- Use `Sunset` header with a date when the endpoint will be removed.
- Mark deprecated fields in schema with `deprecated: true`.

### **Security**
- Define `securitySchemes` (e.g., OAuth2, Bearer token).
- Apply security per operation (not globally) for granular control.
- Never include secrets or credentials in examples or default values.

### **Tags (One Per Bounded Context)**
- Assign one Title-Case English tag per bounded context.
- Group operations under their originating BC's tag for clear domain organization.
- Example tags: `"User Accounts"`, `"Billing"`, `"Order Fulfillment"`.
- See [zalando-checklist.md § Tags](zalando-checklist.md#tags).

### **One File Per Bounded Context (or Consolidate if Needed)**
- Default: Split the API specification by domain/bounded context.
- Naming: `<bounded-context>.openapi.yaml` in `api-specs/` folder (kebab-case).
- Each BC spec is independently publishable to SwaggerHub; minimize cross-file `$ref`.
- Alternative: Consolidate multiple BCs into a single API file; use tags to denote BC boundaries.
- See [bounded-context-mapping.md](bounded-context-mapping.md).

## OpenAPI 3.1 Minimal Skeleton

```yaml
openapi: 3.1.0
info:
  title: "<Bounded Context> API"
  version: "1.0.0"
  description: |
    RESTful API for <bounded context description>.
    Follows Zalando RESTful API Guidelines and RFC 9457 for error responses.
  contact:

From fmflurry/settings-opencode, MIT.

More from fmflurry/settings-opencode