Για προγραμματιστές

Μια προδιαγραφή για να χτίσετε πάνω της.

Το Open Brand Exchange είναι μια προδιαγραφή με τρία API, σχήματα JSON, δεδομένα δοκιμών και δοκιμές συμμόρφωσης. Η προδιαγραφή είναι η πηγή αλήθειας· οι υλοποιήσεις την ακολουθούν.

Τεκμηρίωση API Προδιαγραφή

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

Η προδιαγραφή

Έκδοση 0.1. OpenAPI 3.1, JSON Schema 2020-12, παραδείγματα και μια φανταστική μάρκα δοκιμών, η Kestrel Outfitters. Άδεια CC-BY-4.0: ελεύθερη υλοποίηση, και εμπορικά.

openbrandexchange/spec · Ξεκινήστε από το protocol.md

Τρία API

API	Για	Κατάσταση	Σύμβαση
OBX Protocol	το λογισμικό των μεταπωλητών: discovery, OAuth2 client credentials, ροή αλλαγών, αναζήτηση GTIN, renditions, εξαγωγές, webhooks	κανονιστικό	`obx-protocol.yaml` · HTML
OBX Ingest API	η αυτοματοποίηση μιας μάρκας: idempotent upserts με τα δικά της αναγνωριστικά, μεταφορτώσεις με διευθυνσιοδότηση sha256, παρτίδες, εισαγωγές	κανονιστικό	`obx-ingest.yaml` · HTML
Node Admin + Portal API	η κοινή διαχείριση και η πύλη μεταπωλητών	μη κανονιστικό	`node-admin.yaml` · HTML

Ανάγνωση της πύλης μιας μάρκας σε λίγες γραμμές

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 και εργαλείο γραμμής εντολών

Το obx-go περιέχει το Go SDK (τύποι, πελάτη πρωτοκόλλου και πελάτη ingest με αποδιπλασιασμό, μεταφορτώσεις σε τμήματα και παρτίδες), το εργαλείο obx για μάρκες, το obx-conformance και έναν εικονικό διακομιστή. Σε άλλες γλώσσες αρκεί οποιοσδήποτε πελάτης HTTP: η σύμβαση βρίσκεται στα αρχεία OpenAPI.

obx-go · obx

Συμμόρφωση

Μια υλοποίηση συμμορφώνεται με το OBX για ένα προφίλ όταν το obx-conformance περνά όλες τις υποχρεωτικές δοκιμές του προφίλ. Υπάρχουν τέσσερα προφίλ: protocol, ingest, portal και 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

Υλοποιήσεις

Αποθετήριο	Τι	Άδεια	Κατάσταση
spec	προδιαγραφή, σχήματα, δεδομένα δοκιμών	CC-BY-4.0	0.1
obx-go	Go SDK, εργαλείο obx, δοκιμές συμμόρφωσης, εικονικός διακομιστής	Apache-2.0	0.1
admin-ui	κοινή διεπαφή web: διαχείριση και πύλη μεταπωλητών	Apache-2.0	0.1
node-go	Πύλη για Google Cloud και Docker Go: Docker και Google Cloud Run	AGPL-3.0	0.1
node-php	Πύλη για φιλοξενία ιστού PHP: απλή φιλοξενία ιστού	AGPL-3.0	0.1
node-ts	Πύλη για Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Φτιάχνετε δική σας υλοποίηση ή πελάτη; Ενημερώστε μας με ένα issue ή pull request· θα μπει σε αυτόν τον πίνακα μόλις περάσει τις δοκιμές συμμόρφωσης.

Έγγραφα

Οι συνεισφορές γίνονται με pull requests στο αποθετήριο spec. Πώς λαμβάνονται οι αποφάσεις.