SDK-Muster in TypeScript und Python

Ein Client, einmal konfiguriert

Beide SDKs lesen den Schlüssel aus der Umgebung, er läuft also nie durch Ihren eigenen Code. Bauen Sie den Client auf Modulebene und teilen Sie ihn: jede Instanz hält eigenen Connection-Pool, eigenes Retry-Budget und eigenen ETag-Speicher, und ein Client je Anfrage wirft alle drei jedes Mal weg. Die SDK-Referenz dokumentiert jede Methode.

1import { GunSpec, MemoryETagStore } from '@buun_group/gunspec-sdk'2 3// One client per process, built once and shared. Each instance keeps4// its own connection pool, retry budget and ETag store, so a client5// per request throws all three away on every request.6export const gunspec = new GunSpec({7  apiKey: process.env.GUNSPEC_API_KEY,8  timeout: 10_000,9  // Transient failures only, with backoff and jitter. Terminal10  // answers are never retried.11  retry: { maxRetries: 3 },12  // Revalidation, handled for you: a repeat read sends13  // If-None-Match and a 304 costs nothing against the daily cap.14  etagCache: new MemoryETagStore(),15})

• Setzen Sie ein Timeout. Der Standard ist großzügig, und eine Anfrage, die nie zurückkehrt, ist schlimmer als eine, die scheitert.
• etagCache macht aus wiederholten Lesezugriffen bedingte Anfragen, und ein 304 zählt nicht gegen das Tageslimit.
• Python liefert einen synchronen und einen asynchronen Client mit derselben Oberfläche, sodass ein FastAPI-Dienst und ein Cron-Skript eine Integration teilen.
• Der Schlüssel gehört weiterhin auf einen Server. Kein SDK macht einen Browser sicher, was Schlüssel im Produktivbetrieb behandelt.

Ergebnisse mit dem SDK durchblättern

Beide SDKs laufen die Seiten für Sie durch und hören bei einer kurzen Seite auf, der Durchlauf verhält sich also gleich, ob ein Tarif eine Gesamtzahl meldet oder nicht. Handgeschriebene Schleifen gegen totalPages lesen auf Explorer genau eine Seite. Paginierung nennt die Grenzen je Tarif.

1// on every plan, including the ones that are not told the total.2for await (const firearm of gunspec.firearms.listAutoPaging({ category: 'rifle', per_page: 100 })) {3  await upsert(firearm)4}

Typisierte Fehler, und worauf man verzweigt

Jeder Fehlschlag ist eine Exception mit reason, status, details und requestId. Verzweigen Sie über den Grund, protokollieren Sie die Request-ID, und lassen Sie Fehler behandeln entscheiden, was eine Wiederholung lohnt.

1import { APIError, RateLimitError } from '@buun_group/gunspec-sdk'2 3try {4  return await gunspec.firearms.getAttachments(id)5} catch (err) {6  if (err instanceof RateLimitError) return retryLater(err)7  if (err instanceof APIError) {8    // Branch on reason, never on the message. Both are always9    // present, and requestId is what support needs.10    if (err.reason === 'PLAN_REQUIRED') return upsellFitment()11    log.error({ reason: err.reason, requestId: err.requestId }, 'gunspec')12  }13  throw err14}

Dateien statt JSON

Einige Antworten sind Bytes: das 3D-Modell, Bildderivate, die SVG-Zeichnungen. Sie kommen als Raw-Response mit Body, Content-Type und der URL, von der die Bytes nach einer CDN-Weiterleitung stammen. Das Bildmaterial rendern behandelt, welche Form Sie anfordern.

1// Some responses are files rather than JSON: the 3D model, an2// image derivative, the bullet drawing. Those return raw bytes with3// the content type and the final URL after any CDN redirect.4const model = await gunspec.firearms.getModel('glock-g17')5await writeFile('glock-g17.glb', model.body)6console.log(model.contentType, model.body.byteLength)

Wo der Client hingehört

Vier übliche Formen, mit einer gemeinsamen Regel: der Schlüssel bleibt auf der Serverseite Ihrer eigenen Grenze.