Fejlesztőknek

Specifikáció, amelyre építhet.

Az Open Brand Exchange egy specifikáció három API-val, JSON-sémákkal, tesztadatokkal és megfelelőségi tesztekkel. A specifikáció a mérvadó; az implementációk ezt követik.

API-referencia Specifikáció

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

A specifikáció

0.1-es verzió. OpenAPI 3.1, JSON Schema 2020-12, példák és egy kitalált tesztmárka, a Kestrel Outfitters. Licenc CC-BY-4.0: szabadon implementálható, üzleti célra is.

openbrandexchange/spec · Kezdje a protocol.md fájllal

Három API

API	Kinek	Állapot	Szerződés
OBX Protocol	a viszonteladók szoftverei: discovery, OAuth2 client credentials, változásfolyam, GTIN-keresés, renditions, exportok, webhookok	normatív	`obx-protocol.yaml` · HTML
OBX Ingest API	egy márka automatizálása: idempotens upsertek a márka saját azonosítói alapján, sha256-címzett feltöltések, kötegek, importok	normatív	`obx-ingest.yaml` · HTML
Node Admin + Portal API	a közös adminisztráció és a viszonteladói portál	nem normatív	`node-admin.yaml` · HTML

Egy márkaportál olvasása néhány sorban

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 és parancssori eszköz

Az obx-go tartalmazza a Go SDK-t (típusok, protokollkliens és ingest-kliens deduplikációval, többrészes feltöltéssel és kötegekkel), a márkáknak szóló obx eszközt, az obx-conformance-t és egy álszervert. Más nyelveken bármely HTTP-kliens megfelel: a szerződés az OpenAPI-fájlokban van.

obx-go · obx

Megfelelőség

Egy implementáció akkor OBX-megfelelő egy profilra, ha az obx-conformance a profil minden kötelező tesztjén átmegy. Négy profil van: protocol, ingest, portal és 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ációk

Tároló	Mi	Licenc	Állapot
spec	specifikáció, sémák, tesztadatok	CC-BY-4.0	0.1
obx-go	Go SDK, obx eszköz, megfelelőségi tesztek, álszerver	Apache-2.0	0.1
admin-ui	közös webes felület: adminisztráció és viszonteladói portál	Apache-2.0	0.1
node-go	Portál Google Cloudra és Dockerre Go: Docker és Google Cloud Run	AGPL-3.0	0.1
node-php	Portál webtárhelyre PHP: hagyományos webtárhely	AGPL-3.0	0.1
node-ts	Portál Cloudflare-re TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Saját implementációt vagy klienst épít? Jelezze issue-ban vagy pull requestben; amint átmegy a megfelelőségi teszteken, bekerül ebbe a táblázatba.

Dokumentumok

A hozzájárulás a spec tárolóba küldött pull requestekkel történik. Hogyan születnek a döntések.