Pre vývojárov

Špecifikácia, na ktorej môžete stavať.

Open Brand Exchange je špecifikácia s tromi API, schémami JSON, testovacími údajmi a testami zhody. Špecifikácia je zdrojom pravdy; implementácie sa ňou riadia.

Referencia API Špecifikácia

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"]
}

Špecifikácia

Verzia 0.1. OpenAPI 3.1, JSON Schema 2020-12, príklady a fiktívna testovacia značka Kestrel Outfitters. Licencia CC-BY-4.0: voľne implementovateľné, aj komerčne.

openbrandexchange/spec · Začnite súborom protocol.md

Tri API

API	Pre	Stav	Kontrakt
OBX Protocol	softvér predajcov: discovery, OAuth2 client credentials, kanál zmien, vyhľadávanie podľa GTIN, renditions, exporty, webhooky	normatívne	`obx-protocol.yaml` · HTML
OBX Ingest API	automatizácia značky: idempotentné upserty podľa vlastných ID značky, nahrávanie adresované sha256, dávky, importy	normatívne	`obx-ingest.yaml` · HTML
Node Admin + Portal API	zdieľaná administrácia a portál pre predajcov	nenormatívne	`node-admin.yaml` · HTML

Čítanie portálu značky na pár riadkoch

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 a nástroj pre príkazový riadok

obx-go obsahuje Go SDK (typy, klienta protokolu a ingest klienta s deduplikáciou, viacdielnym nahrávaním a dávkami), nástroj obx pre značky, obx-conformance a mock server. V iných jazykoch stačí akýkoľvek HTTP klient: kontrakt je v súboroch OpenAPI.

obx-go · obx

Zhoda

Implementácia je v zhode s OBX pre daný profil, keď obx-conformance prejde všetkými povinnými testami tohto profilu. Existujú štyri profily: protocol, ingest, portal a 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ácie

Repozitár	Čo	Licencia	Stav
spec	špecifikácia, schémy, testovacie údaje	CC-BY-4.0	0.1
obx-go	Go SDK, nástroj obx, testy zhody, mock server	Apache-2.0	0.1
admin-ui	zdieľané webové rozhranie: administrácia a portál pre predajcov	Apache-2.0	0.1
node-go	Portál pre Google Cloud a Docker Go: Docker a Google Cloud Run	AGPL-3.0	0.1
node-php	Portál pre webhosting PHP: bežný webhosting	AGPL-3.0	0.1
node-ts	Portál pre Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Staviate vlastnú implementáciu alebo klienta? Dajte vedieť cez issue alebo pull request; do tabuľky sa dostane, len čo prejde testami zhody.

Dokumenty

Príspevky prebiehajú cez pull requesty v repozitári spec. Ako sa prijímajú rozhodnutia.