Developers

A specification you can build on.

Open Brand Exchange is a specification with three APIs, JSON Schemas, test data and a conformance suite. The specification is the source of truth; the implementations follow it.

API reference Specification

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

The specification

Version 0.1. OpenAPI 3.1, JSON Schema 2020-12, examples and a fictional test brand, Kestrel Outfitters. Licensed CC-BY-4.0: free to implement, commercially too.

openbrandexchange/spec · Start with protocol.md

Three APIs

API	For	Status	Contract
OBX Protocol	retailers' software: discovery, OAuth2 client credentials, change feed, GTIN lookup, renditions, exports, webhooks	normative	`obx-protocol.yaml` · HTML
OBX Ingest API	a brand's automation: idempotent upserts keyed by the brand's own ids, sha256-addressed uploads, batches, imports	normative	`obx-ingest.yaml` · HTML
Node Admin + Portal API	the shared admin and retailer portal	non-normative	`node-admin.yaml` · HTML

Reading a brand portal in a few lines

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 and command-line tool

obx-go contains the Go SDK (types, a protocol client and an ingest client with deduplication, multipart uploads and batching), the obx tool for brands, obx-conformance and a mock server. In other languages any HTTP client works: the contract is in the OpenAPI files.

obx-go · obx

Conformance

An implementation is OBX-conformant for a profile when obx-conformance passes every required test of that profile. There are four profiles: protocol, ingest, portal and 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

Implementations

Repository	What	Licence	Status
spec	specification, schemas, test data	CC-BY-4.0	0.1
obx-go	Go SDK, obx tool, conformance suite, mock server	Apache-2.0	0.1
admin-ui	shared web interface: admin and retailer portal	Apache-2.0	0.1
node-go	Portal for Google Cloud & Docker Go: Docker and Google Cloud Run	AGPL-3.0	0.1
node-php	Portal for web hosting PHP: ordinary web hosting	AGPL-3.0	0.1
node-ts	Portal for Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Building your own implementation or consumer? Let us know with an issue or pull request, and it goes into this table once it passes the conformance suite.

Documents

Contributions go through pull requests on the spec repository. How decisions are made.