Sviluppatori

Una specifica su cui costruire.

Open Brand Exchange è una specifica con tre API, JSON Schema, dati di test e test di conformità. La specifica è il riferimento; le implementazioni la seguono.

Riferimento API Specifica

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

La specifica

Versione 0.1. OpenAPI 3.1, JSON Schema 2020-12, esempi e un brand di test fittizio, Kestrel Outfitters. Licenza CC-BY-4.0: libera da implementare, anche commercialmente.

openbrandexchange/spec · Inizia da protocol.md

Tre API

API	Per	Stato	Contratto
OBX Protocol	i software dei rivenditori: discovery, OAuth2 client credentials, feed delle modifiche, ricerca per GTIN, renditions, export, webhook	normativa	`obx-protocol.yaml` · HTML
OBX Ingest API	l'automazione di un brand: upsert idempotenti sugli ID propri del brand, upload indirizzati per sha256, lotti, import	normativa	`obx-ingest.yaml` · HTML
Node Admin + Portal API	l'amministrazione condivisa e l'area rivenditori	non normativa	`node-admin.yaml` · HTML

Leggere il portale di un brand in poche righe

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 e strumento da riga di comando

obx-go contiene l'SDK Go (tipi, un client del protocollo e un client ingest con deduplicazione, upload multipart e lotti), lo strumento obx per i brand, obx-conformance e un server fittizio. In altri linguaggi va bene qualsiasi client HTTP: il contratto è nei file OpenAPI.

obx-go · obx

Conformità

Un'implementazione è conforme OBX per un profilo quando obx-conformance supera tutti i test obbligatori di quel profilo. I profili sono quattro: protocol, ingest, portal e 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

Implementazioni

Repository	Cosa	Licenza	Stato
spec	specifica, schemi, dati di test	CC-BY-4.0	0.1
obx-go	SDK Go, strumento obx, test di conformità, server fittizio	Apache-2.0	0.1
admin-ui	interfaccia web condivisa: amministrazione e area rivenditori	Apache-2.0	0.1
node-go	Portale per Google Cloud e Docker Go: Docker e Google Cloud Run	AGPL-3.0	0.1
node-php	Portale per web hosting PHP: normale web hosting	AGPL-3.0	0.1
node-ts	Portale per Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Stai costruendo una tua implementazione o un client? Faccelo sapere con una issue o una pull request; entrerà in questa tabella appena supera i test di conformità.

Documenti

I contributi passano tramite pull request sul repository spec. Come si prendono le decisioni.