Bewährte Praktiken für API-Client-SDKs

Generiere den Low-Level-Client aus einer OpenAPI-Spezifikation und schreibe von Hand nur eine dünne, idiomatische Schicht darüber. Konfidenz: 0.85 Behandle die API-Spezifikation als Quelle der Wahrheit und lasse CI fehlschlagen, wenn der generierte Code veraltet ist. Konfidenz: 0.85 Ermögliche den ersten Aufruf in drei Zeilen: installieren, einen Client mit einem API-Schlüssel erstellen, eine Methode aufrufen. Konfidenz: 0.90 Lies den API-Schlüssel standardmäßig aus einer bekannten Umgebungsvariable und protokolliere ihn niemals oder nimm ihn in Fehlermeldungen auf. Konfidenz: 0.95 Stelle vollständig typisierte Anfrage- und Antwortmodelle bereit, mit TypeScript-Typen oder Python-Typ-Hinweisen, die im Paket enthalten sind. Konfidenz: 0.90 Gib typisierte Fehler mit HTTP-Status, Fehlercode, Nachricht und Anfrage-ID zurück, anstatt einer generischen Ausnahme. Konfidenz: 0.90 Wiederhole idempotente Anfragen bei Zeitüberschreitungen, 429- und 5xx-Antworten mit exponentiellem Backoff und Jitter und respektiere Retry-After-Header. Konfidenz: 0.90 Sende automatisch einen Idempotenz-Schlüssel bei wiederholten POST-Anfragen, wenn die API dies unterstützt. Konfidenz: 0.80 Lege sinnvolle Standard-Zeitüberschreitungen fest und erlaube Aufrufern, Zeitüberschreitungs- und Wiederholungseinstellungen pro Client und pro Anfrage zu überschreiben. Konfidenz: 0.85 Stelle automatisch paginierende Iteratoren bereit, damit Benutzer über alle Ergebnisse iterieren können, ohne Cursor selbst zu verwalten. Konfidenz: 0.85 Unterstütze Streaming-Antworten mit nativen asynchronen Iteratoren oder Generatoren anstelle von Callbacks. Konfidenz: 0.80 Biete sowohl synchrone als auch asynchrone Clients in Sprachen an, in denen beide üblich sind, und teile dieselben Modelle. Konfidenz: 0.75 Halte Laufzeitabhängigkeiten minimal und vermeide es, Benutzer auf eine bestimmte HTTP-Bibliotheksversion festzulegen. Konfidenz: 0.85 Sende einen User-Agent-Header mit SDK-Name, Version und Laufzeit, damit API-Besitzer die Nutzung sehen und Probleme debuggen können. Konfidenz: 0.80 Befolge semantische Versionierung strikt und dokumentiere breaking changes mit Migrationsbeispielen im Changelog. Konfidenz: 0.90 Entferne niemals eine Methode in einem Minor-Release; kennzeichne sie zuerst mit einer Warnung als veraltet. Konfidenz: 0.85 Teste gegen aufgezeichnete HTTP-Fixtures für Geschwindigkeit und führe nachts eine kleinere Suite gegen eine echte Sandbox-Umgebung aus. Konfidenz: 0.80 Führe die Testsuite in CI auf jeder unterstützten Laufzeitversion aus, wie jeder aktiven Node.js-LTS- oder Python-Version. Konfidenz: 0.85 Füge ausführbare Codebeispiele in README und Dokumentation ein und teste diese Beispiele in CI, damit sie nie veralten. Konfidenz: 0.80 Stelle Hooks oder Middleware für Protokollierung, Tracing und benutzerdefinierte Header bereit, anstatt einmalige Optionen für jeden Bedarf hinzuzufügen. Konfidenz: 0.75 Erlaube eine benutzerdefinierte Basis-URL und einen HTTP-Client, damit Benutzer das SDK auf Proxys, Mocks oder regionale Endpunkte ausrichten können. Konfidenz: 0.80 Veröffentliche Pakete aus CI mit Herkunft und signierten Releases, niemals vom Laptop eines Maintainers. Konfidenz: 0.75