Entwickler

Eine Spezifikation, auf die Sie bauen können.

Open Brand Exchange ist eine Spezifikation mit drei APIs, JSON-Schemas, Testdaten und Konformitätstests. Die Spezifikation ist die Quelle; die Implementierungen folgen ihr.

API-Referenz Spezifikation

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

Die Spezifikation

Version 0.1. OpenAPI 3.1, JSON Schema 2020-12, Beispiele und eine fiktive Testmarke, Kestrel Outfitters. Lizenz CC-BY-4.0: frei implementierbar, auch kommerziell.

openbrandexchange/spec · Beginnen Sie mit protocol.md

Drei APIs

API	Für	Status	Vertrag
OBX Protocol	Software von Händlern: Discovery, OAuth2 Client Credentials, Änderungsfeed, GTIN-Suche, Renditions, Exporte, Webhooks	normativ	`obx-protocol.yaml` · HTML
OBX Ingest API	die Automatisierung einer Marke: idempotente Upserts über die eigenen IDs der Marke, Uploads per sha256, Stapel, Importe	normativ	`obx-ingest.yaml` · HTML
Node Admin + Portal API	die gemeinsame Verwaltung und das Händlerportal	nicht normativ	`node-admin.yaml` · HTML

Ein Markenportal in wenigen Zeilen auslesen

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 und Kommandozeilen-Tool

obx-go enthält das Go-SDK (Typen, einen Protokoll-Client und einen Ingest-Client mit Deduplizierung, Multipart-Uploads und Stapeln), das obx-Tool für Marken, obx-conformance und einen Mock-Server. In anderen Sprachen funktioniert jeder HTTP-Client: Der Vertrag steht in den OpenAPI-Dateien.

obx-go · obx

Konformität

Eine Implementierung ist OBX-konform für ein Profil, wenn obx-conformance alle Pflichttests dieses Profils besteht. Es gibt vier Profile: protocol, ingest, portal und 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

Implementierungen

Repository	Was	Lizenz	Status
spec	Spezifikation, Schemas, Testdaten	CC-BY-4.0	0.1
obx-go	Go-SDK, obx-Tool, Konformitätstests, Mock-Server	Apache-2.0	0.1
admin-ui	gemeinsame Weboberfläche: Verwaltung und Händlerportal	Apache-2.0	0.1
node-go	Portal für Google Cloud & Docker Go: Docker und Google Cloud Run	AGPL-3.0	0.1
node-php	Portal für Webhosting PHP: normales Webhosting	AGPL-3.0	0.1
node-ts	Portal für Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Sie bauen eine eigene Implementierung oder einen Abnehmer? Melden Sie sich per Issue oder Pull Request; sobald die Konformitätstests bestanden sind, kommt sie in diese Tabelle.

Dokumente

Beiträge laufen über Pull Requests im spec-Repository. Wie Entscheidungen getroffen werden.