Definition
数字产品护照 API 如何组织？
大致围绕四类资源。护照保存产品记录及其访问策略。事件记录对象经历了什么，按 GS1 EPCIS 2.0 序列化。凭证以 W3C Verifiable Credentials 承载签名声明。解析则把 GS1 Digital Link 标识转换为调用方有权获得的视图。
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.
模型
哪个资源回答哪个问题
| Resource | 答疑 | 标准 |
|---|---|---|
| Passport | "What is this product, and who may see which part?" | 符合 CIRPASS 的模型 |
| 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 |
答疑
常见问题
API 的核心资源有哪些？
四类。护照保存产品记录及其访问策略。事件记录对象经历了什么，按 EPCIS 2.0 序列化。凭证以 W3C Verifiable Credentials 承载签名声明。解析则是读取路径：输入一个 GS1 Digital Link 标识，输出适配调用方的视图。
什么时候该写入事件，而不是更新护照？
当您在更正或补全护照的描述时，请更新护照。当确有事情发生时——某个步骤完成、保管权转移、完成一次维修——请写入事件。经验法则是：护照字段回答“这是什么”，事件回答“它经历了什么”。
为什么解析与读取护照是两件不同的事？
因为解析正是扫描所做的事，它是公开、匿名且可缓存的。通过 API 读取护照则需要认证，并只返回您的密钥所对应的内容。二者服务于不同的调用方、提供不同的保证，把它们混为一谈会让公开路径背上私有路径的成本。
API 有版本管理吗？
有，在路径中——所有内容都位于 `/v1` 之下。新增性变更不会提升版本号；任何会破坏既有集成的变更都会启用新版本并设置重叠期。护照记录本身单独进行版本管理，因为一份护照的存续时间长于它被创建时所用的任何 API 版本。