Ein SDK über einer HTTP-API entwerfen

Ziel

Eine Client-Bibliothek ausliefern, mit der ein Integrator – Mensch oder Agent – die API nutzen kann, ohne die HTTP-Details lesen zu müssen, ohne die Semantik der API zu verschleiern und ohne dass das SDK zu einer zweiten, separat zu pflegenden API wird.

Voraussetzungen

Eine maschinenlesbare API-Beschreibung (OpenAPI oder Protobuf), die als einzige Quelle der Wahrheit dient; eine Versionierungsrichtlinie für die API; eine Entscheidung, welche Sprachen zuerst unterstützt werden, ausgerichtet daran, wer integriert.

Schritte

1. Die Transportschicht (Modelle, Serialisierung, Endpunktaufrufe) aus der Beschreibung generieren; nie von Hand pflegen, was die Beschreibung bereits festlegt. Generierten Code in einem eigenen Paket oder Verzeichnis halten, damit handgeschriebener Code eine Neugenerierung übersteht.
2. Ein einzelnes Client-Objekt hinzufügen, das die Konfiguration besitzt: Basis-URL, Anmeldedaten, Timeouts, Wiederholungsrichtlinie, einen User-Agent mit der SDK-Version. Anmeldedaten zuerst aus Parametern und erst danach aus Umgebungsvariablen lesen; keine Konfigurationsdateien erfinden.
3. HTTP-Fehler auf einen einzigen Exception- oder Ergebnistyp abbilden, der Status, den Fehlertext der API, die Request-ID und die Information trägt, ob der Fehler wiederholbar ist. Nicht je Endpunkt unterschiedliche Typen werfen.
4. Wiederholungen einmalig in der Transportschicht implementieren: nur für idempotente Aufrufe oder Aufrufe mit einem vom SDK erzeugten Idempotenzschlüssel; exponentielles Backoff mit Jitter; Retry-After beachten; die Gesamtzeit begrenzen.
5. Pagination als Iterator kapseln, der Seiten bei Bedarf abruft, und den rohen Seitenaufruf für Aufrufer offenlegen, die Kontrolle benötigen.
6. Lang laufende Operationen mit einem Wait-Helper kapseln, der anhand der Hinweise des Servers und einer Frist pollt und entweder das Ergebnis oder den Fehler der Operation zurückgibt.
7. Das SDK unabhängig von der API mit semantischer Versionierung versehen; die Hauptversion des SDK ändert sich, wenn dessen eigene Schnittstelle bricht, nicht wenn die API ein Feld hinzufügt.
8. In der CI gegen einen aufgezeichneten Server oder eine Sandbox testen und regelmässig gegen die Live-Sandbox; ein Änderungsprotokoll veröffentlichen, das für jede SDK-Version die Ziel-API-Version nennt.
9. Die README als Tutorial für den ersten Aufruf schreiben: installieren, konfigurieren, ein Aufruf, ein behandelter Fehler; alles Weitere auf die API-Referenz verlinken.

Erwartetes Ergebnis

Integratoren schreiben weniger Code und stossen auf weniger Fehler bei Wiederholungen und Pagination, und das Verhalten des SDK stimmt mit der dokumentierten API-Semantik überein, weil der grösste Teil generiert ist.

Grenzen und Prüfbasis

Ein vorgeschlagenes Vorgehen; es wird kein Vergleich zwischen SDK-Designs behauptet. Handgeschriebene Komfortfunktionen (Builder, Hilfsmittel, die mehrere Aufrufe kombinieren) sind die Stelle, an der SDKs von der API abweichen; sie schlank halten und in der Dokumentation als Komfortfunktionen kennzeichnen.