API overview
Vier resources, en de relaties daartussen
Paspoorten beschrijven. Gebeurtenissen leggen vast. Credentials bewijzen. Resolutie levert. Die vier vooraf scherp hebben, voorkomt dat een integratie na een half jaar weer moet worden afgebroken.
- Basispad
- /v1
- Formaat
- JSON over HTTPS
- Auth
- Bearer-sleutels met scope
Definition
Hoe is de paspoort-API opgebouwd?
Rond vier resources. Paspoorten bevatten het productrecord en het toegangsbeleid daarvan. Gebeurtenissen leggen vast wat er met een object gebeurde, geserialiseerd als GS1 EPCIS 2.0. Credentials dragen ondertekende claims als W3C Verifiable Credentials. Resolutie maakt van een GS1 Digital Link-identificator de weergave waar een aanroeper recht op heeft.
Each serialises somebody else’s standard — EPCIS 2.0, VC 2.0 and GS1 Digital Link — so what you build against these endpoints keeps working against a conforming implementation that is not ours.
Het model
Welke resource welke vraag beantwoordt
| Resource | Antwoorden | Standaard |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | CIRPASS-conform model |
| Event | "What happened to this object, where and when?" | GS1 EPCIS 2.0 (JSON-LD) |
| Credential | "Who asserted this, and can I check it myself?" | W3C Verifiable Credentials 2.0 |
| Resolution | "Someone scanned this — what do they get?" | GS1 Digital Link |
Endpoints
Het oppervlak, in het kort
Paspoorten
Productrecord aanmaken, lezen, bijwerken en versioneren. Gaprapportage tegen de productgroep.
Gebeurtenissen
Voeg EPCIS 2.0-gebeurtenissen toe en bevraag de volledige historie van één objectidentiteit.
Credentials
Ondertekende claims op een paspoort uitgeven, tonen, verifiëren en intrekken.
Resolutie
Het publieke leespad dat een scan volgt, met teruggave van het bij de aanroeper passende niveau.
Authenticatie
Bearer-sleutels met scope, per omgeving en per functie.
Volledige referentie
Elk endpoint, elke parameter, elke responsvorm en elke foutcode.
Antwoorden
Veelgestelde vragen
Wat zijn de kernresources van de API?
Vier. Paspoorten bevatten het productrecord en het toegangsbeleid daarvan. Gebeurtenissen leggen vast wat er met een object gebeurde, geserialiseerd als EPCIS 2.0. Credentials dragen ondertekende claims als W3C Verifiable Credentials. Resolutie is het leespad: een GS1 Digital Link-identificator erin, de voor de aanroeper passende weergave eruit.
Wanneer schrijf ik een gebeurtenis in plaats van het paspoort bij te werken?
Werk het paspoort bij wanneer u de beschrijving corrigeert of aanvult. Schrijf een gebeurtenis wanneer er iets is gebeurd — een stap voltooid, beheer overgedragen, een reparatie uitgevoerd. Vuistregel: een paspoortveld beantwoordt “wat is dit?” en een gebeurtenis beantwoordt “wat is ermee gebeurd?”.
Waarom is resolutie iets anders dan een paspoort lezen?
Omdat resolutie is wat een scan doet, en die is publiek, anoniem en cachebaar. Een paspoort lezen via de API is geauthenticeerd en geeft terug waar uw sleutel recht op heeft. Zij bedienen verschillende aanroepers met verschillende garanties, dus ze samenvoegen zou betekenen dat het publieke pad de kosten van het private erft.
Is de API geversioneerd?
Ja, in het pad — alles staat onder `/v1`. Additieve wijzigingen gaan live zonder versiesprong; alles dat een bestaande integratie zou breken krijgt een nieuwe versie met een overlapperiode. Paspoortrecords zelf worden apart geversioneerd, omdat een paspoort elke API-versie overleeft waaronder het is gemaakt.
Next step
Daarna de referentie lezen
U hebt nu het model. De referentie bevat het schema, de parameters en het foutcontract.