Dla programistów

Specyfikacja, na której możesz budować.

Open Brand Exchange to specyfikacja z trzema API, schematami JSON, danymi testowymi i testami zgodności. Specyfikacja jest źródłem prawdy; implementacje za nią podążają.

Dokumentacja API Specyfikacja

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

Specyfikacja

Wersja 0.1. OpenAPI 3.1, JSON Schema 2020-12, przykłady i fikcyjna marka testowa Kestrel Outfitters. Licencja CC-BY-4.0: swobodna implementacja, także komercyjna.

openbrandexchange/spec · Zacznij od protocol.md

Trzy API

API	Dla	Status	Kontrakt
OBX Protocol	oprogramowanie sprzedawców: discovery, OAuth2 client credentials, strumień zmian, wyszukiwanie po GTIN, renditions, eksporty, webhooki	normatywne	`obx-protocol.yaml` · HTML
OBX Ingest API	automatyzacja marki: idempotentne upserty po własnych identyfikatorach marki, przesyłanie adresowane sha256, paczki, importy	normatywne	`obx-ingest.yaml` · HTML
Node Admin + Portal API	wspólny panel administracyjny i portal dla sprzedawców	nienormatywne	`node-admin.yaml` · HTML

Odczyt portalu marki w kilku linijkach

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 i narzędzie wiersza poleceń

obx-go zawiera SDK Go (typy, klienta protokołu i klienta ingest z deduplikacją, przesyłaniem wieloczęściowym i paczkami), narzędzie obx dla marek, obx-conformance i serwer atrapę. W innych językach wystarczy dowolny klient HTTP: kontrakt jest w plikach OpenAPI.

obx-go · obx

Zgodność

Implementacja jest zgodna z OBX dla danego profilu, gdy obx-conformance zalicza wszystkie obowiązkowe testy tego profilu. Są cztery profile: protocol, ingest, portal i 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

Implementacje

Repozytorium	Co	Licencja	Status
spec	specyfikacja, schematy, dane testowe	CC-BY-4.0	0.1
obx-go	SDK Go, narzędzie obx, testy zgodności, serwer atrapa	Apache-2.0	0.1
admin-ui	wspólny interfejs WWW: panel administracyjny i portal dla sprzedawców	Apache-2.0	0.1
node-go	Portal dla Google Cloud i Dockera Go: Docker i Google Cloud Run	AGPL-3.0	0.1
node-php	Portal na hosting WWW PHP: zwykły hosting WWW	AGPL-3.0	0.1
node-ts	Portal dla Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Tworzysz własną implementację lub klienta? Daj znać przez issue lub pull request; trafi do tej tabeli, gdy przejdzie testy zgodności.

Dokumenty

Wkład odbywa się przez pull requesty w repozytorium spec. Jak podejmowane są decyzje.