Za razvijalce

Specifikacija, na kateri lahko gradite.

Open Brand Exchange je specifikacija s tremi API-ji, shemami JSON, testnimi podatki in testi skladnosti. Specifikacija je vir resnice; implementacije ji sledijo.

Referenca API Specifikacija

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

Specifikacija

Različica 0.1. OpenAPI 3.1, JSON Schema 2020-12, primeri in izmišljena testna znamka Kestrel Outfitters. Licenca CC-BY-4.0: prosto za implementacijo, tudi komercialno.

openbrandexchange/spec · Začnite s protocol.md

Trije API-ji

API	Za	Stanje	Pogodba
OBX Protocol	programska oprema trgovcev: discovery, OAuth2 client credentials, tok sprememb, iskanje po GTIN, renditions, izvozi, webhooki	normativen	`obx-protocol.yaml` · HTML
OBX Ingest API	avtomatizacija znamke: idempotentni upserti po lastnih ID-jih znamke, nalaganja naslovljena s sha256, paketi, uvozi	normativen	`obx-ingest.yaml` · HTML
Node Admin + Portal API	skupno skrbništvo in portal za trgovce	nenormativen	`node-admin.yaml` · HTML

Branje portala znamke v nekaj vrsticah

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 in orodje za ukazno vrstico

obx-go vsebuje Go SDK (tipe, odjemalca protokola in odjemalca ingest z odstranjevanjem dvojnikov, večdelnim nalaganjem in paketi), orodje obx za znamke, obx-conformance in navidezni strežnik. V drugih jezikih zadošča kateri koli odjemalec HTTP: pogodba je v datotekah OpenAPI.

obx-go · obx

Skladnost

Implementacija je skladna z OBX za profil, ko obx-conformance opravi vse obvezne teste tega profila. Obstajajo štirje profili: protocol, ingest, portal in 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

Implementacije

Repozitorij	Kaj	Licenca	Stanje
spec	specifikacija, sheme, testni podatki	CC-BY-4.0	0.1
obx-go	Go SDK, orodje obx, testi skladnosti, navidezni strežnik	Apache-2.0	0.1
admin-ui	skupni spletni vmesnik: skrbništvo in portal za trgovce	Apache-2.0	0.1
node-go	Portal za Google Cloud in Docker Go: Docker in Google Cloud Run	AGPL-3.0	0.1
node-php	Portal za spletno gostovanje PHP: običajno spletno gostovanje	AGPL-3.0	0.1
node-ts	Portal za Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Gradite lastno implementacijo ali odjemalca? Sporočite nam prek issue ali pull request; v tabelo pride, ko opravi teste skladnosti.

Dokumenti

Prispevki potekajo prek pull requestov v repozitoriju spec. Kako se sprejemajo odločitve.