Kehittäjille

Määrittely, jonka varaan voit rakentaa.

Open Brand Exchange on määrittely, jossa on kolme APIa, JSON Schemat, testidata ja yhdenmukaisuustestit. Määrittely on lähde; toteutukset seuraavat sitä.

API-dokumentaatio Määrittely

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

Määrittely

Versio 0.1. OpenAPI 3.1, JSON Schema 2020-12, esimerkit ja kuvitteellinen testibrändi Kestrel Outfitters. Lisenssi CC-BY-4.0: vapaasti toteutettavissa, myös kaupallisesti.

openbrandexchange/spec · Aloita tiedostosta protocol.md

Kolme APIa

API	Kenelle	Tila	Sopimus
OBX Protocol	jälleenmyyjien ohjelmistot: discovery, OAuth2 client credentials, muutossyöte, GTIN-haku, renditions, viennit, webhookit	normatiivinen	`obx-protocol.yaml` · HTML
OBX Ingest API	brändin automaatio: idempotentit upsertit brändin omilla tunnisteilla, sha256-osoitteiset lataukset, erät, tuonnit	normatiivinen	`obx-ingest.yaml` · HTML
Node Admin + Portal API	yhteinen hallinta ja jälleenmyyjäportaali	ei-normatiivinen	`node-admin.yaml` · HTML

Lue brändin portaali muutamalla rivillä

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 ja komentorivityökalu

obx-go sisältää Go-SDK:n (tyypit, protokollaclientin sekä ingest-clientin kaksoiskappaleiden poistolla, multipart-latauksilla ja erillä), obx-työkalun brändeille, obx-conformancen ja mock-palvelimen. Muilla kielillä mikä tahansa HTTP-client käy: sopimus on OpenAPI-tiedostoissa.

obx-go · obx

Yhdenmukaisuus

Toteutus on OBX-yhdenmukainen profiilin osalta, kun obx-conformance läpäisee kaikki profiilin pakolliset testit. Profiileja on neljä: protocol, ingest, portal ja 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

Toteutukset

Repositorio	Mitä	Lisenssi	Tila
spec	määrittely, skeemat, testidata	CC-BY-4.0	0.1
obx-go	Go-SDK, obx-työkalu, yhdenmukaisuustestit, mock-palvelin	Apache-2.0	0.1
admin-ui	yhteinen verkkokäyttöliittymä: hallinta ja jälleenmyyjäportaali	Apache-2.0	0.1
node-go	Portaali Google Cloudille ja Dockerille Go: Docker ja Google Cloud Run	AGPL-3.0	0.1
node-php	Portaali webhotelliin PHP: tavallinen webhotelli	AGPL-3.0	0.1
node-ts	Portaali Cloudflarelle TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Rakennatko oman toteutuksen tai asiakkaan? Kerro siitä issuella tai pull requestilla; se lisätään taulukkoon, kun se läpäisee yhdenmukaisuustestit.

Dokumentit

Osallistuminen tapahtuu pull requesteilla spec-repositorioon. Miten päätökset tehdään.