REST-API-Contract entwerfen

Entwirft Endpunkte für ein Feature mit Pfaden, Status-Codes, Request/Response-Shape, Pagination und Fehlerformat.

Zuletzt geprüft 23. April 2026

Prompt

Design a REST API contract for this feature. Assume JSON over HTTPS.

Produce:
1. RESOURCES - list of nouns, hierarchy (e.g., /projects/:id/tasks)
2. ENDPOINTS table - for each:
   - Method + Path
   - Purpose (1 sentence)
   - Request shape (fields + types, required/optional)
   - Response shape (success + example)
   - Status codes used (specifically which 4xx)
3. ERROR FORMAT - a single consistent error envelope (problem+json or custom), used for all 4xx/5xx
4. PAGINATION - which endpoint paginates, cursor vs offset, shape
5. AUTH - how (bearer / session / API key), which endpoints are public
6. VERSIONING - strategy (URL prefix vs header vs none)
7. OPEN QUESTIONS - what the spec needs before it can be built

Rules:
- No RPC-style verbs in paths ("/getUser" is banned)
- No 200 with `error: true` in body - use proper status code
- Sparse fields / partial responses: only if feature demands it
- Idempotency for non-GET mutations where it matters (PUT yes, POST sometimes via idempotency key)
- Do not invent requirements - list them as open questions

Feature:
[FEATURE DESCRIPTION + EXPECTED CLIENTS]

Wann nutzen

Für den Design-Moment bevor Endpoints codiert werden. Verhindert Endpoint-Chaos und macht Fehlerformat + Pagination früh verbindlich.

Use-Cases

  • Neues Backend-Feature, Frontend-Team wartet auf Contract.
  • Refactor einer gewachsenen API: Soll-Struktur skizzieren.
  • Third-Party-Integration: saubere externe Schnittstelle.

Getestet mit

Die Open Questions oft wertvoller als das Design. Fehlende Antworten (“was passiert, wenn Task gelöscht wird, aber Comments existieren?”) müssen geklärt werden, bevor Code entsteht.