За разработчици

Спецификация, върху която да градите.

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, експорти, уебкуки	нормативен	`obx-protocol.yaml` · HTML
OBX Ingest API	автоматизацията на марката: идемпотентни upsert операции по собствените ID на марката, качвания, адресирани чрез 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	общ уеб интерфейс: администрация и портал за търговци	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. Как се вземат решенията.