SDKs
Dunne clients, en een noodluik dat werkelijk werkt
Typen uit hetzelfde schema waartegen de API valideert, retries die de rate-headers respecteren, en handtekeningverificatie die u anders subtiel verkeerd zou doen. Al het overige is één ruwe request verderop.
- Getypeerd vanuit
- Het API-schema
- Hoofdversie
- Volgt /v1
- Ruwe requests
- Altijd beschikbaar
Definition
Wat levert een clientbibliotheek voor de paspoort-API u op?
Typen gegenereerd uit het schema waartegen de API valideert, zodat een verkeerd veld faalt bij het compileren in plaats van als runtimefout. Retry en backoff die de rate-limit-headers respecteren. Webhook-handtekeningverificatie over de ruwe body. En een noodluik voor verzoeken die de client niet modelleert.
None of it is essential. Every payload is JSON following a published standard, so an integration written with an HTTP client and no SDK at all is a completely reasonable choice — and one some security policies require.
Clients
Wat er beschikbaar is
| Language | Typical use | Notes |
|---|---|---|
| TypeScript / Node.js | Storefronts, webhook receivers, serverless issuing | Types generated from the schema; works in edge runtimes |
| Python | Data pipelines, PLM and ERP integration jobs | Fits where the sustainability data work already happens |
| Go | High-throughput event ingestion services | For services writing events continuously rather than in batches |
| Anything else | Direct HTTP | JSON, GS1 and W3C standards — no client required |
Vorm
Hoe het gebruik eruitziet
import { CirculeID } from '@circuleid/sdk';
const circuleid = new CirculeID({ apiKey: process.env.CIRCULEID_API_KEY });
const passport = await circuleid.passports.create({
gtin: '09506000134352',
productGroup: 'textiles',
level: 'model',
record: { name: 'Merino Crew Knit' },
});
// The gap report is part of the response, not a separate call:
// which fields the delegated act still requires for this group.
console.log(passport.gaps);
// Escape hatch — same auth, same retries, no abstraction in the way.
await circuleid.request('POST', '/v1/events', { body: epcisEvent });Waar zij voor zorgen
De onderdelen die u beter niet zelf schrijft
Gegenereerde typen
Uit hetzelfde schema waartegen de API valideert, zodat de twee niet uit elkaar kunnen lopen.
Retry en backoff
Leest de rate-limitheaders en past jitter toe, zodat parallelle workers zich gedragen.
Handtekeningverificatie
Over de ruwe body, in constante tijd — de twee details die mensen fout doen.
Paginering
Cursorafhandeling voor lange gebeurtenishistories, aangeboden als asynchrone iterator.
Ontsnappingsluik
Willekeurige requests met hetzelfde auth- en retrygedrag als de getypeerde aanroepen.
Voorspelbare versionering
De major volgt de API-versie; de minor voegt toe, herdefinieert nooit.
Antwoorden
Veelgestelde vragen
Wat doen de SDK’s meer dan HTTP inpakken?
Drie dingen zijn de moeite waard: typen die worden gegenereerd uit hetzelfde schema waartegen de API valideert, zodat een verkeerd veld een compileerfout is in plaats van een 400; retry en backoff die de rate-limit-headers respecteren; en verificatie van webhook-handtekeningen, die je makkelijk subtiel verkeerd implementeert door een opnieuw geserialiseerde body te hashen in plaats van de ruwe.
Kan ik nog steeds ruwe requests doen?
Ja, en de clients zijn daarop gebouwd. Elke client biedt een noodluik dat een willekeurig verzoek stuurt met dezelfde authenticatie en hetzelfde retrygedrag. Een SDK die u door zijn abstracties dwingt, is er een waartegen u vecht zodra u iets nodig hebt dat hij niet had voorzien.
Hoe verhouden SDK-versies zich tot API-versies?
De hoofdversie volgt de API-versie, dus een v1-client spreekt met /v1. Minor-releases voegen endpoints en velden toe naarmate de API groeit. Een client verandert binnen een hoofdversie niet stilzwijgend van gedrag — nieuwe velden verschijnen, bestaande veranderen niet van betekenis.
Welke taal moeten wij voor de uitgiftepijplijn gebruiken?
De taal die uw ops-team al draait. Het uitgiftepad is een geplande job die met uw PLM en met ons praat; het is niet prestatiegevoelig en wordt onderhouden door wie ook uw andere integraties onderhoudt. Een taal kiezen die daar niemand kent, is hier de meest vermijdbare fout.
Zijn de clients open source?
De clients worden gegenereerd uit een gepubliceerd schema, en de gegenereerde broncode is leesbaar en mee te leveren. Moet u er een forken om aan intern beleid te voldoen, dan hangt niets in het protocol af van onze client — elke payload volgt GS1- of W3C-standaarden die u rechtstreeks zou kunnen implementeren.
Next step
Begin in de taal die uw team al draait
De uitgiftepijplijn wordt onderhouden door wie ook uw andere integraties onderhoudt. Optimaliseer daarvoor, niet voor nieuwigheid.