Desarrolladores

Una especificación sobre la que construir.

Open Brand Exchange es una especificación con tres API, JSON Schemas, datos de prueba y pruebas de conformidad. La especificación es la referencia; las implementaciones la siguen.

Referencia de la API Especificación

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 especificación

Versión 0.1. OpenAPI 3.1, JSON Schema 2020-12, ejemplos y una marca de prueba ficticia, Kestrel Outfitters. Licencia CC-BY-4.0: libre de implementar, también comercialmente.

openbrandexchange/spec · Empieza por protocol.md

Tres API

API	Para	Estado	Contrato
OBX Protocol	el software de los distribuidores: discovery, OAuth2 client credentials, feed de cambios, búsqueda por GTIN, renditions, exportaciones, webhooks	normativa	`obx-protocol.yaml` · HTML
OBX Ingest API	la automatización de una marca: upserts idempotentes con los identificadores propios de la marca, subidas por sha256, lotes, importaciones	normativa	`obx-ingest.yaml` · HTML
Node Admin + Portal API	la administración compartida y el portal para distribuidores	no normativa	`node-admin.yaml` · HTML

Leer el portal de una marca en pocas líneas

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 y herramienta de línea de comandos

obx-go contiene el SDK de Go (tipos, un cliente de protocolo y un cliente de ingest con deduplicación, subidas multipart y lotes), la herramienta obx para marcas, obx-conformance y un servidor simulado. En otros lenguajes sirve cualquier cliente HTTP: el contrato está en los archivos OpenAPI.

obx-go · obx

Conformidad

Una implementación es conforme a OBX para un perfil cuando obx-conformance supera todas las pruebas obligatorias de ese perfil. Hay cuatro perfiles: protocol, ingest, portal y 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

Implementaciones

Repositorio	Qué	Licencia	Estado
spec	especificación, esquemas, datos de prueba	CC-BY-4.0	0.1
obx-go	SDK de Go, herramienta obx, pruebas de conformidad, servidor simulado	Apache-2.0	0.1
admin-ui	interfaz web compartida: administración y portal para distribuidores	Apache-2.0	0.1
node-go	Portal para Google Cloud y Docker Go: Docker y Google Cloud Run	AGPL-3.0	0.1
node-php	Portal para alojamiento web PHP: alojamiento web normal	AGPL-3.0	0.1
node-ts	Portal para Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

¿Estás creando tu propia implementación o un consumidor? Avísanos con una issue o una pull request; entrará en esta tabla en cuanto supere las pruebas de conformidad.

Documentos

Las contribuciones se hacen mediante pull requests en el repositorio spec. Cómo se toman las decisiones.