Programadores

Uma especificação sobre a qual construir.

O Open Brand Exchange é uma especificação com três APIs, JSON Schemas, dados de teste e testes de conformidade. A especificação é a referência; as implementações seguem-na.

Referência da API Especificação

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

A especificação

Versão 0.1. OpenAPI 3.1, JSON Schema 2020-12, exemplos e uma marca de teste fictícia, Kestrel Outfitters. Licença CC-BY-4.0: livre de implementar, também comercialmente.

openbrandexchange/spec · Comece por protocol.md

Três APIs

API	Para	Estado	Contrato
OBX Protocol	o software dos revendedores: discovery, OAuth2 client credentials, feed de alterações, pesquisa por GTIN, renditions, exportações, webhooks	normativa	`obx-protocol.yaml` · HTML
OBX Ingest API	a automatização de uma marca: upserts idempotentes pelos identificadores próprios da marca, envios endereçados por sha256, lotes, importações	normativa	`obx-ingest.yaml` · HTML
Node Admin + Portal API	a administração partilhada e o portal de revendedores	não normativa	`node-admin.yaml` · HTML

Ler o portal de uma marca em poucas linhas

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 e ferramenta de linha de comandos

O obx-go contém o SDK Go (tipos, um cliente de protocolo e um cliente de ingest com desduplicação, envios multipart e lotes), a ferramenta obx para marcas, o obx-conformance e um servidor simulado. Noutras linguagens serve qualquer cliente HTTP: o contrato está nos ficheiros OpenAPI.

obx-go · obx

Conformidade

Uma implementação é conforme com o OBX para um perfil quando o obx-conformance passa todos os testes obrigatórios desse perfil. Há quatro perfis: protocol, ingest, portal e 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

Implementações

Repositório	O quê	Licença	Estado
spec	especificação, esquemas, dados de teste	CC-BY-4.0	0.1
obx-go	SDK Go, ferramenta obx, testes de conformidade, servidor simulado	Apache-2.0	0.1
admin-ui	interface web partilhada: administração e portal de revendedores	Apache-2.0	0.1
node-go	Portal para Google Cloud e Docker Go: Docker e Google Cloud Run	AGPL-3.0	0.1
node-php	Portal para alojamento web PHP: alojamento web comum	AGPL-3.0	0.1
node-ts	Portal para Cloudflare TypeScript: Cloudflare Workers	AGPL-3.0	0.1

Está a criar a sua própria implementação ou um consumidor? Avise-nos com uma issue ou pull request; entra nesta tabela assim que passar nos testes de conformidade.

Documentos

As contribuições fazem-se por pull requests no repositório spec. Como são tomadas as decisões.