API Overview

The backend serves two REST APIs over JSON: one for the CMS and back-office tools, one for storefronts. Both are described by generated OpenAPI 3.1 specs, and both follow one set of rules for URLs, pagination and errors.

Two APIs

	Admin API	Storefront API
URL	/api/<module>/v2/admin/…	/api/<module>/v2/<channel_idx>/…
Caller	the CMS, back-office jobs	storefronts, widgets, server jobs
Credential	a staff JWT in Authorization: Bearer	none for catalog and content reads; a customer JWT or an application token in X-API-KEY where the operation names one
Spec	594 operations on 407 paths	53 operations on 52 paths

An admin route may carry a channel after admin/ (/api/pim/v2/admin/<channel_idx>/products/) or none (/api/pim/v2/admin/channels/). Most storefront routes name their channel: Channels in the URL.

The three credentials, how to get each and how long it lives: Authentication.

Explorers and Specs

• CMS Admin API: every admin operation, grouped by module. Spec: volkanos-api-admin.yaml.
• Storefront API: the storefront operations. Spec: volkanos-api-storefront.yaml.

Each explorer sends its requests to one of two servers, picked in its server list:

• https://demo-api.entirius.com, the public demo and the default. Shared data, reset every day at 04:00 UTC; the login is in Demo Credentials.
• http://localhost:8100, your own stack from the Quickstart.

The specs hold the v2 operations and the two staff token routes, and are generated from the running backend; the info.version of a spec is the backend release it came from (Versioning).

Your First Request

Every command below is shown twice: against the public demo first, then against your own stack.

Ask for a staff token. On the demo, viewer / viewer is a read-only login:

curl -s -X POST https://demo-api.entirius.com/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "viewer", "password": "viewer"}'

On your own stack, admin / admin123 is the user the local seed creates:

curl -s -X POST http://localhost:8100/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Both answer a token pair:

{"refresh": "<refresh token>", "access": "<access token>"}

Keep the access value in a variable and list the sales channels through the admin API. The token lives 5 minutes; after that the call answers 401 and the refresh token gets a new one.

ACCESS="<access token>"
# or take it straight from the login (needs jq):
ACCESS=$(curl -s -X POST https://demo-api.entirius.com/api/token/ -H "Content-Type: application/json" \
  -d '{"username": "viewer", "password": "viewer"}' | jq -r .access)
curl -s -H "Authorization: Bearer $ACCESS" https://demo-api.entirius.com/api/pim/v2/admin/channels/
curl -s -H "Authorization: Bearer $ACCESS" http://localhost:8100/api/pim/v2/admin/channels/

A token works only on the server that issued it. The demo answers its three channels:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {"pk": 2, "idx": "sloik-eu", "name": "Jar of Moments", "default_language": "en", "default_currency": "EUR", "languages": ["en", "es", "de", "pl"], "is_default": false, "inheritance_enabled": false, "default_inheritance_flags": []},
    {"pk": 1, "idx": "sloik-pl", "name": "Słoik Chwil", "default_language": "pl", "default_currency": "PLN", "languages": ["en", "pl"], "is_default": false, "inheritance_enabled": false, "default_inheritance_flags": []},
    {"pk": 3, "idx": "sloik-firmy", "name": "Słoik Chwil dla Firm", "default_language": "pl", "default_currency": "PLN", "languages": ["en", "pl"], "is_default": false, "inheritance_enabled": false, "default_inheritance_flags": []}
  ]
}

The local seed has two, default-europe and default-local.

Take an idx from that answer and read two products of that channel from the storefront API. No credential this time: catalog reads are public.

curl -s "https://demo-api.entirius.com/api/matrix/v2/sloik-pl/products/?page_size=2"
curl -s "http://localhost:8100/api/matrix/v2/default-europe/products/?page_size=2"

The demo answer, with each product cut down to three of its fields:

{
  "has_next_page": true,
  "page": 1,
  "page_size": 2,
  "results": [
    {"sku": "SC-POD-011", "name": "Gwiazdy nad pustynią", "product_type": "SIMPLE"},
    {"sku": "SC-POD-008", "name": "Zorza polarna", "product_type": "SIMPLE"}
  ],
  "meta": {"status": "ok", "warnings": []}
}

The two lists answer in two different envelopes on purpose: Pagination.

To see who the token belongs to and what it may do, call GET /api/access/v2/me/: the answer and its fields are in Staff Tokens. A request without a token gets 401, and a route outside the viewer’s role gets 403: When It Fails.

Next Steps

• Authentication: staff tokens, customer tokens and application tokens.
• Conventions: channels, languages, pagination, sorting, filtering, errors and rate limits.
• Versioning: what the v2 in the URL promises.

Sources

• main/urls.py of the service: the token routes.
• django_pim/api/admin/urls.py: the admin channel list.
• django_matrix/urls.py: the storefront product list.
• Makefile of the harness, target schema: how the two specs are generated.