Pentru dezvoltatori

O specificație pe care puteți construi.

Open Brand Exchange este o specificație cu trei API-uri, scheme JSON, date de test și teste de conformitate. Specificația este sursa de adevăr; implementările o urmează.

Referință API Specificație

Terminal

$ curl https://brands.kestrel.example/.well-known/obx

200 OK · application/json

{
  "obx_version": "0.1",
  "publisher": { "name": "Kestrel Outfitters" },
  "api_base": "https://brands.kestrel.example/obx/v1",
  "portal_url": "https://brands.kestrel.example/",
  "capabilities": ["changes", "products", "by_gtin",
                   "renditions", "exports", "webhooks"]
}

Specificația

Versiunea 0.1. OpenAPI 3.1, JSON Schema 2020-12, exemple și o marcă de test fictivă, Kestrel Outfitters. Licență CC-BY-4.0: liber de implementat, inclusiv comercial.

openbrandexchange/spec · Începeți cu protocol.md

Trei API-uri

API	Pentru	Stare	Contract
OBX Protocol	software-ul comercianților: discovery, OAuth2 client credentials, flux de modificări, căutare după GTIN, renditions, exporturi, webhookuri	normativ	`obx-protocol.yaml` · HTML
OBX Ingest API	automatizarea unei mărci: upserturi idempotente după ID-urile proprii ale mărcii, încărcări adresate prin sha256, loturi, importuri	normativ	`obx-ingest.yaml` · HTML
Node Admin + Portal API	administrarea comună și portalul pentru comercianți	nenormativ	`node-admin.yaml` · HTML

Citirea portalului unei mărci în câteva rânduri

HOST=https://brands.kestrel.example
curl -s $HOST/.well-known/obx                       # what does this brand offer?
TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials \
  $HOST/obx/v1/oauth/token | jq -r .access_token)
curl -s -H "Authorization: Bearer $TOKEN" "$HOST/obx/v1/changes?limit=500"   # everything, then only changes
curl -s -H "Authorization: Bearer $TOKEN" -X POST -H 'Content-Type: application/json' \
  -d '{"gtins":["2000100101025"]}' "$HOST/obx/v1/products:by-gtin"
# or let the obx tool keep a copy in a folder, only fetching what changed:
OBX_CLIENT_ID=$CLIENT_ID OBX_CLIENT_SECRET=$CLIENT_SECRET obx pull $HOST --out ./kestrel

SDK și instrument de linie de comandă

obx-go conține SDK-ul Go (tipuri, un client de protocol și un client ingest cu deduplicare, încărcări multipart și loturi), instrumentul obx pentru mărci, obx-conformance și un server simulat. În alte limbaje, orice client HTTP funcționează: contractul este în fișierele OpenAPI.

obx-go · obx

Conformitate

O implementare este conformă OBX pentru un profil când obx-conformance trece toate testele obligatorii ale acelui profil. Există patru profiluri: protocol, ingest, portal și security. conformance.md

obx-conformance all --url http://localhost:8080 --setup-code …   # a fresh portal: setup, fixtures, every profile
obx-conformance protocol --url https://brands.kestrel.example --client-id obxc_… --client-secret obxs_…
obx-conformance mock                                              # a mock server that passes everything

Implementări

Depozit	Ce	Licență	Stare
spec	specificație, scheme, date de test	CC-BY-4.0	0.1
obx-go	SDK Go, instrumentul obx, teste de conformitate, server simulat	Apache-2.0	0.1
admin-ui	interfață web comună: administrare și portal pentru comercianți	Apache-2.0	0.1
node-go	Portal pentru Google Cloud și Docker Go: Docker și Google Cloud Run	AGPL-3.0	0.1
node-php	Portal pentru găzduire web PHP: găzduire web obișnuită	AGPL-3.0	0.1
node-ts	Portal pentru Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Construiți propria implementare sau un client? Anunțați-ne printr-un issue sau pull request; intră în acest tabel după ce trece testele de conformitate.

Documente

Contribuțiile se fac prin pull requesturi în depozitul spec. Cum se iau deciziile.