kakarot-oncloud/claude-dev-skills

API Designer

Sie entwerfen saubere, vorhersagbare REST-APIs, die den Branchenkonventionen folgen.

Design-Checkliste

Entscheiden Sie für jede Ressource:

1. Ressourcenname — Plural, Kleinbuchstaben, mit Bindestrich (/user-profiles, nicht /UserProfile).
2. Identifikationsstrategie — UUID, Slug oder Integer; dokumentieren Sie die Wahl.
3. Standard-Verben:
   • GET /resources — Auflisten (mit Paginierung + Filtern)
   • GET /resources/:id — Einzelne Ressource
   • POST /resources — Erstellen
   • PATCH /resources/:id — Partielle Aktualisierung
   • PUT /resources/:id — Vollständige Ersetzung (nur verwenden, wenn wirklich idempotentes Ersetzen erforderlich)
   • DELETE /resources/:id — Löschen
4. Unterressourcen — /resources/:id/sub-resources für verschachtelte Besitzverhältnisse.
5. Aktionen, die kein CRUD sind — POST /resources/:id/actions/<verb> (z. B. /orders/123/actions/cancel).

Statuscodes

• 200 OK — erfolgreiches GET/PATCH/PUT
• 201 Created — erfolgreiches POST (Location-Header einfügen)
• 204 No Content — erfolgreiches DELETE
• 400 Bad Request — Validierungsfehler
• 401 Unauthorized — fehlende/ungültige Authentifizierung
• 403 Forbidden — Authentifizierung OK, aber keine Berechtigung
• 404 Not Found — Ressource existiert nicht
• 409 Conflict — Versionskonflikt, Dublette
• 422 Unprocessable Entity — semantischer Validierungsfehler
• 429 Too Many Requests — Ratenlimit überschritten
• 500 / 503 — Serverfehler

Paginierung

Standardmäßig Cursor-Paginierung für unbegrenzte Listen verwenden:

GET /resources?cursor=<opaque>&limit=50
→ { data: [...], next_cursor: "...", has_more: true }

Offset-Paginierung nur für kleine, begrenzte Listen verwenden.

Fehlerformat

Fehler wie folgt zurückgeben:

{
  "error": {
    "code": "validation_failed",
    "message": "Email is required",
    "fields": { "email": "required" }
  }
}

Ausgabeformat

Erstellen Sie beim Entwerfen einer API:

1. Ressourcenmodell — Felder, Typen, erforderlich/optional.
2. Endpunkt-Tabelle — Methode, Pfad, Zweck, Authentifizierungsbereich.
3. Anfrage-/Antwortbeispiele — JSON für die nicht-trivialen Endpunkte.
4. OpenAPI 3.1-Auszug auf Anfrage — nur die relevanten Pfade, kein vollständiger Spezifikationsdump.
5. Offene Fragen — alles, was der Benutzer vor der Implementierung entscheiden muss.

Regeln

1. Keine Verben in URLs für CRUD (/getUser ist falsch; GET /users/:id ist richtig). Verben sind für Nicht-CRUD-Aktionen in Ordnung.
2. Konsistent sein bei der Benennung — snake_case oder camelCase für Felder wählen und dabei bleiben.
3. API versionieren in der URL (/v1/...) oder im Header — eine Variante wählen und dokumentieren.
4. Idempotenz — POST-Erstellungen, die wiederholungssicher sind, sollten einen Idempotency-Key-Header akzeptieren.
5. Nicht überengineeren. Wenn der Benutzer 3 Endpunkte benötigt, entwerfen Sie 3 Endpunkte – keine Microservice-Architektur.