Ontwikkelaars

Een specificatie waarop je kunt bouwen.

Open Brand Exchange is een specificatie met drie API's, JSON Schema's, testdata en een conformancetest. De specificatie is de bron; de implementaties volgen haar.

API-referentie Specificatie

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

De specificatie

Versie 0.1. OpenAPI 3.1, JSON Schema 2020-12, voorbeelden en een fictief testmerk, Kestrel Outfitters. Licentie CC-BY-4.0: vrij te implementeren, ook commercieel.

openbrandexchange/spec · Begin bij protocol.md

Drie API's

API	Voor	Status	Contract
OBX Protocol	software van retailers: discovery, OAuth2 client credentials, wijzigingsfeed, opzoeken op GTIN, renditions, exports, webhooks	normatief	`obx-protocol.yaml` · HTML
OBX Ingest API	de automatisering van een merk: idempotente upserts op de eigen id's van het merk, uploads op sha256, batches, imports	normatief	`obx-ingest.yaml` · HTML
Node Admin + Portal API	de gedeelde beheeromgeving en het retailerportaal	niet-normatief	`node-admin.yaml` · HTML

Een merkportaal uitlezen in een paar regels

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 en commandline-tool

obx-go bevat de Go-SDK (types, een protocolclient en een ingestclient met ontdubbeling, multipart-uploads en batches), de obx-tool voor merken, obx-conformance en een mockserver. In andere talen werkt elke HTTP-client: het contract staat in de OpenAPI-bestanden.

obx-go · obx

Conformance

Een implementatie is OBX-conformant voor een profiel als obx-conformance alle verplichte tests van dat profiel haalt. Er zijn vier profielen: protocol, ingest, portal en 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

Implementaties

Repository	Wat	Licentie	Status
spec	specificatie, schema's, testdata	CC-BY-4.0	0.1
obx-go	Go-SDK, obx-tool, conformancetest, mockserver	Apache-2.0	0.1
admin-ui	gedeelde webinterface: beheer en retailerportaal	Apache-2.0	0.1
node-go	Portaal voor Google Cloud & Docker Go: Docker en Google Cloud Run	AGPL-3.0	0.1
node-php	Portaal voor webhosting PHP: gewone webhosting	AGPL-3.0	0.1
node-ts	Portaal voor Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Bouw je zelf een implementatie of een afnemer? Laat het weten met een issue of pull request; hij komt in deze tabel zodra hij de conformancetest haalt.

Documenten

Bijdragen gaan via pull requests op de spec-repository. Hoe beslissingen worden genomen.