API reference
すべてのエンドポイントを、リソースごとに整理
パスポート、イベント、クレデンシャル、解決。以下のエラー契約、ページネーション、冪等性の規則は、四つすべてに一律に適用されます。
- ベースURL
- api.circuleid.com
- バージョン
- /v1
- 認証
- Bearer
Definition
パスポート API はどのようなエンドポイントを提供しますか。
四つのグループです。パスポートのエンドポイントは製品レコードの発行、読み取り、更新、バージョン管理を行います。イベントのエンドポイントはEPCIS 2.0のイベントを追加・照会します。クレデンシャルのエンドポイントは署名済みの主張を発行、検証、失効させます。解決のエンドポイントは、スキャンされたデータキャリアがたどる公開のGS1 Digital Linkパスを提供します。
If you have not read the API model yet, start there. The relationships between these four decide which one you should be calling, and that is the choice most integrations get wrong first.
エンドポイント
パスポート
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/passports | Issue a passport against a GS1 identifier |
| GET | /v1/passports/{id} | Read the full record your key is entitled to |
| PATCH | /v1/passports/{id} | Update the record; material changes are versioned |
| GET | /v1/passports/{id}/gaps | Fields the product group’s delegated act still requires |
| GET | /v1/passports/{id}/versions | The record’s version history |
| GET | /v1/passports | List and filter passports in your tenant |
エンドポイント
イベント
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/events | Append one EPCIS 2.0 event |
| POST | /v1/events/bulk | Asynchronous bulk ingestion; returns a job |
| GET | /v1/events | Query by object identity, business step or time |
| GET | /v1/jobs/{id} | Status of a bulk ingestion job |
エンドポイント
クレデンシャル
| 方法 | Path | Purpose |
|---|---|---|
| POST | /v1/credentials | Issue a signed claim against a passport |
| GET | /v1/credentials/{id} | Retrieve a credential and its status |
| POST | /v1/credentials/{id}/revoke | Revoke; verification fails from this point |
| POST | /v1/credentials/verify | Verify a credential you were presented |
エンドポイント
解決
| 方法 | Path | Purpose |
|---|---|---|
| GET | /01/{gtin} | GS1 Digital Link resolution — the path a scan takes |
| GET | /01/{gtin}/21/{serial} | Resolution for an item-level passport |
規約
エラー、ページネーション、冪等性
# Validation errors return every problem at once.
HTTP/1.1 422 Unprocessable Entity
{
"error": "validation_failed",
"problems": [
{ "field": "materials[0].share", "constraint": "must sum to 1.0" },
{ "field": "carbonFootprint.method", "constraint": "required for this group" }
]
}
# Pagination is cursor-based: an offset would skip or repeat
# records as new events arrive while you are reading.
GET /v1/events?object=01/09506000134352&cursor=ev_8f21...
# Send an idempotency key on any write you might retry.
POST /v1/passports
Idempotency-Key: 6f1c9a7e-... # a repeat returns the original result回答
よくある質問
エラー応答はどのような形ですか。
一般的なHTTPステータスと、エラー、失敗したフィールド、違反した制約を示す構造化されたボディを返します。検証エラーは一件ずつではなくすべてまとめて返すため、不正な製品レコードは5往復ではなく1回の応答で全問題が判明します。
ページネーションはどう扱われますか。
オフセットではなくカーソル方式です。イベント履歴は読み取っている最中にも増えるため、オフセットでは新しいイベントの到着に伴い、レコードを黙って飛ばしたり重複させたりします。カーソルは不透明かつ安定しています。前のページが返したものを渡し、返ってこなくなったら停止してください。
書き込みは冪等ですか。
可能ですし、そうすべきです。再試行の可能性がある書き込みには冪等キーを付けてください。同じキーでの再実行は、2つ目のパスポートや重複イベントを作らず、元の結果を返します。キーがなければ、書き込み時のネットワークタイムアウトによって、それが適用されたかどうかを判断できなくなります。
パスポートを読むことと解決することの違いは何ですか。
読み取りは認証を伴い、APIキーが許す範囲を返します。解決はスキャンの動作です。公開・匿名・キャッシュ可能で、呼び出し元のクレデンシャルが許す階層 — 大半の呼び出し元にとっては公開階層 — を返します。両者は別の経路であり、性能とプライバシーの性質も異なります。