Utviklere

En spesifikasjon du kan bygge på.

Open Brand Exchange er en spesifikasjon med tre API-er, JSON Schemas, testdata og samsvarstester. Spesifikasjonen er kilden; implementasjonene følger den.

API-referanse Spesifikasjon

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

Spesifikasjonen

Versjon 0.1. OpenAPI 3.1, JSON Schema 2020-12, eksempler og en fiktiv testmerkevare, Kestrel Outfitters. Lisens CC-BY-4.0: fritt å implementere, også kommersielt.

openbrandexchange/spec · Start med protocol.md

Tre API-er

API	For	Status	Kontrakt
OBX Protocol	forhandleres programvare: discovery, OAuth2 client credentials, endringsstrøm, GTIN-oppslag, renditions, eksporter, webhooks	normativ	`obx-protocol.yaml` · HTML
OBX Ingest API	en merkevares automatisering: idempotente upserts på merkevarens egne ID-er, opplastinger adressert med sha256, bunker, importer	normativ	`obx-ingest.yaml` · HTML
Node Admin + Portal API	den felles administrasjonen og forhandlerportalen	ikke-normativ	`node-admin.yaml` · HTML

Les en merkevareportal på noen få linjer

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 og kommandolinjeverktøy

obx-go inneholder Go-SDK-et (typer, en protokollklient og en ingest-klient med deduplisering, multipart-opplasting og bunker), obx-verktøyet for merkevarer, obx-conformance og en mockserver. I andre språk fungerer enhver HTTP-klient: kontrakten står i OpenAPI-filene.

obx-go · obx

Samsvar

En implementasjon er OBX-samsvarende for en profil når obx-conformance består alle obligatoriske tester i profilen. Det finnes fire profiler: protocol, ingest, portal og 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

Implementasjoner

Repo	Hva	Lisens	Status
spec	spesifikasjon, skjemaer, testdata	CC-BY-4.0	0.1
obx-go	Go-SDK, obx-verktøy, samsvarstester, mockserver	Apache-2.0	0.1
admin-ui	felles nettgrensesnitt: administrasjon og forhandlerportal	Apache-2.0	0.1
node-go	Portal for Google Cloud og Docker Go: Docker og Google Cloud Run	AGPL-3.0	0.1
node-php	Portal for webhotell PHP: vanlig webhotell	AGPL-3.0	0.1
node-ts	Portal for Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Bygger du din egen implementasjon eller klient? Gi beskjed med et issue eller en pull request; den kommer i tabellen så snart den består samsvarstestene.

Dokumenter

Bidrag skjer via pull requests i spec-repoet. Hvordan beslutninger tas.