Développeurs

Une spécification sur laquelle bâtir.

Open Brand Exchange est une spécification avec trois API, des schémas JSON, des données de test et des tests de conformité. La spécification fait foi ; les implémentations la suivent.

Référence de l'API Spécification

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

La spécification

Version 0.1. OpenAPI 3.1, JSON Schema 2020-12, des exemples et une marque de test fictive, Kestrel Outfitters. Licence CC-BY-4.0 : libre à implémenter, y compris commercialement.

openbrandexchange/spec · Commencez par protocol.md

Trois API

API	Pour	Statut	Contrat
OBX Protocol	les logiciels des revendeurs : discovery, OAuth2 client credentials, flux de changements, recherche par GTIN, renditions, exports, webhooks	normative	`obx-protocol.yaml` · HTML
OBX Ingest API	l'automatisation d'une marque : upserts idempotents sur les identifiants propres à la marque, envois adressés par sha256, lots, imports	normative	`obx-ingest.yaml` · HTML
Node Admin + Portal API	l'administration partagée et l'espace revendeurs	non normative	`node-admin.yaml` · HTML

Lire un portail de marque en quelques lignes

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 et outil en ligne de commande

obx-go contient le SDK Go (types, un client protocole et un client ingest avec déduplication, envois multipart et lots), l'outil obx pour les marques, obx-conformance et un serveur factice. Dans les autres langages, n'importe quel client HTTP convient : le contrat est dans les fichiers OpenAPI.

obx-go · obx

Conformité

Une implémentation est conforme OBX pour un profil lorsque obx-conformance réussit tous les tests obligatoires de ce profil. Il existe quatre profils : protocol, ingest, portal et 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

Implémentations

Dépôt	Contenu	Licence	Statut
spec	spécification, schémas, données de test	CC-BY-4.0	0.1
obx-go	SDK Go, outil obx, tests de conformité, serveur factice	Apache-2.0	0.1
admin-ui	interface web partagée : administration et espace revendeurs	Apache-2.0	0.1
node-go	Portail pour Google Cloud et Docker Go : Docker et Google Cloud Run	AGPL-3.0	0.1
node-php	Portail pour hébergement web PHP : hébergement web classique	AGPL-3.0	0.1
node-ts	Portail pour Cloudflare TypeScript : Cloudflare Workers	AGPL-3.0	0.1

Vous développez votre propre implémentation ou un client ? Faites-le savoir par une issue ou une pull request ; elle rejoindra ce tableau dès qu'elle réussira les tests de conformité.

Documents

Les contributions passent par des pull requests sur le dépôt spec. Comment les décisions sont prises.