CommunityCodierung & Entwicklunggithub.com

API-Verträge

API-Verträge (REST, gRPC, Protobuf, Events) entwerfen und ändern, sodass bestehende Aufrufer weiterhin funktionieren. Deckt Ressourcen- und Methodenform, Fehlermodelle, Paginierung, Versionierung und die Auslieferungsreihenfolge bei breaking changes ab. Verwenden, wenn ein Endpunkt, eine Nachricht oder ein Event hinzugefügt oder geändert wird, oder um zu beurteilen, ob eine vorgeschlagene Änderung einen Verbraucher bricht.

Was ist API-Verträge?

Dieses Skill hilft Entwicklern und KI-Agenten dabei, API-Verträge (REST, gRPC, Protobuf, Events) zu entwerfen und zu ändern, ohne bestehende Aufrufer zu beeinträchtigen. Es betont, dass ein Vertrag ein Versprechen an Code ist, den man nicht kontrolliert – die Kosten eines Fehlers trägt jemand anderes. Der Skill behandelt bewährte Methoden für das Design (Ressourcen als Nomen, Idempotenz, konsistente Fehlermodelle, Paginierung), identifiziert klar, was einen Aufrufer bricht (z. B. Entfernen eines Feldes, Ändern eines Typs oder Hinzufügen eines erforderlichen Feldes) und was sicher ist (optionale Felder hinzufügen, neue Endpunkte). Er empfiehlt eine sichere Änderungsstrategie („Hinzufügen vor Entfernen“) und spezielle Hinweise für Protobuf (Tag-Reservierung). Zudem wird die Auslieferungsreihenfolge behandelt: Generierter Code und Server werden separat ausgerollt, wobei zuerst die Seite aktualisiert wird, die beide Formen toleriert. Für geteilte Schemas (Gateway, Proxy) müssen alle Komponenten neu generiert und bereitgestellt werden. Abschließend wird empfohlen, tatsächliche Verbraucher zu überprüfen und den Vertrag selbst zu testen. Unterstützte Plattformen sind allgemein API-Entwicklungsumgebungen und Agenten, die mit solchen Systemen interagieren.

Funktioniert mit~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-api

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht API-Verträge?

Ein Vertrag ist ein Versprechen an Code, den Sie nicht kontrollieren und nicht reparieren können. Das unterscheidet API-Änderungen von internem Refactoring: Die Kosten eines Fehlers trägt jemand anderes, zu einem Zeitpunkt, den Sie nicht wählen.

Design

Benennen Sie Ressourcen als Nomen und lassen Sie die Methode das Verb tragen. Modellieren Sie das Ding, nicht den Bildschirm, der es aktuell anzeigt – eine Payload, die um die heutige UI geformt ist, wird beim nächsten Redesign falsch.

Seien Sie bewusst, was Sie offenlegen. Jedes Feld, das Sie zurückgeben, ist ein Feld, das Sie weiterhin zurückgeben müssen. Interne Identifikatoren, Zeilenversionen und Implementierungsdetails lassen Ihr Schema in den Code des Aufrufers durchsickern und frieren es dort ein.

Machen Sie Operationen idempotent, wenn der Aufrufer wiederholen könnte – also jede Operation, die über ein Netzwerk erreichbar ist. Geben Sie dem Aufrufer einen Idempotenzschlüssel für alles, was erstellt oder belastet, damit eine Wiederholung nach einem Timeout nichts verdoppeln kann.

Geben Sie ein konsistentes Fehlermodell zurück: einen stabilen maschinenlesbaren Code, eine menschenlesbare Nachricht und das Feld, auf das sich eine Validierungsfehler bezieht. Aufrufer verzweigen anhand des Codes, also ist er Teil des Vertrags – das Ändern eines Codes ist ein Breaking Change, auch wenn die Form unverändert bleibt.

Paginieren Sie jede Liste ab der ersten Version. Ein Endpunkt, der alles zurückgibt, funktioniert, bis die Tabelle wächst, und scheitert dann für den Kunden mit den meisten Daten. Bevorzugen Sie einen Cursor gegenüber einem Offset, wenn Zeilen gleichzeitig eingefügt werden.

Was einen Aufrufer bricht

Breaking, unabhängig davon, was die Schema-Sprache erlaubt:

  • Entfernen oder Umbenennen eines Feldes, eines Endpunkts, einer Methode oder eines Enum-Werts.
  • Ein optionales Request-Feld erforderlich machen oder die akzeptierten Werte eines Feldes einschränken.
  • Ändern eines Typs, einschließlich Integer zu String und eines einzelnen Werts zu einer Liste.
  • Die Bedeutung eines vorhandenen Feldes ändern, während Name und Typ erhalten bleiben – die schlimmste Art, da nichts laut scheitert und die Daten leise falsch sind.
  • Hinzufügen eines neuen erforderlichen Feldes zu einem Request.
  • Ändern eines Fehlercodes oder eines HTTP-Status für eine bestehende Bedingung.
  • Verschärfen eines Standardwerts oder ändern, was passiert, wenn ein Feld weggelassen wird.

Sicher: Hinzufügen eines optionalen Request-Feldes, Hinzufügen eines Response-Feldes, Hinzufügen eines neuen Endpunkts oder einer neuen Methode, Hinzufügen eines Enum-Werts nur wenn jeder Verbraucher bereits unbekannte Werte toleriert – überprüfen Sie das, statt es anzunehmen.

In Protobuf: Verwenden oder nummerieren Sie ein Feld-Tag niemals wieder, und reservieren Sie das Tag und den Namen, wenn Sie ein Feld entfernen. Ein wiederverwendetes Tag dekodiert alte Daten in das neue Feld und beschädigt sie leise.

Einen Vertrag sicher ändern

Fügen Sie hinzu, bevor Sie entfernen, und lassen Sie beide mindestens eine Version lang funktionieren:

  1. Fügen Sie das neue Feld oder die neue Methode neben dem alten hinzu.
  2. Schreiben Sie beide, lesen Sie das neue mit einem Fallback auf das alte.
  3. Migrieren Sie die Verbraucher und bestätigen Sie, dass jeder umgestellt hat.
  4. Entfernen Sie den alten Pfad in einer späteren Version.

Versionieren Sie, wenn sich die Ressource tatsächlich in ihrer Bedeutung ändert, nicht bei jeder Ergänzung. Eine Version pro Änderung vervielfacht die Oberfläche, die Sie am Leben erhalten müssen.

Auslieferungsreihenfolge

Generierter Code und Server werden separat ausgerollt, und die Lücke ist der Ort, an dem Ausfälle leben. Rollen Sie zuerst die Seite aus, die beide Formen toleriert: Verbraucher, die das neue Feld akzeptieren, bevor Produzenten es senden; Produzenten, die den neuen Request akzeptieren, bevor Aufrufer ihn senden.

Wenn ein Schema über ein Gateway, einen Proxy oder generierte Clients geteilt wird, muss jede Komponente im Pfad neu generiert und bereitgestellt werden. Ein Feld, das zum Dienst hinzugefügt, aber nicht zur davorliegenden Schicht hinzugefügt wurde, verschwindet, bevor es den Aufrufer erreicht, und die eigenen Tests des Dienstes werden es nicht bemerken.

Überprüfen

Überprüfen Sie die tatsächlichen Verbraucher, bevor Sie eine Form ändern – durchsuchen Sie die Aufrufer, statt der Dokumentation des Vertrags zu vertrauen.

Testen Sie den Vertrag selbst: Ein Test, der die serialisierte Form überprüft, fängt eine versehentliche Umbenennung, die ein Unit-Test des Handlers völlig übersehen würde.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Verwandte Skills