Stéphane Tailland
cbbf1e6aa7
The developer portal listed this API with no reference documentation: catalog was the only domain that had a spec anywhere in the tree. Generated from the backend's own drf-spectacular schema (/classic-models/api/schema/, version 4.7.0), filtered to the operations this domain's gateway actually exposes — derived from the Kong routes and their request-transformer rewrites in Konnect, not from guesswork. Every route resolved to a backend operation; the counts match one for one. Paths and server are the **gateway's**, not the backend's. A portal reader calls https://customers-dev.sttlab.local/customers/v1/..., and the gateway rewrites that onto /classic-models/api/v1/... upstream. Path parameters are renamed to the gateway's capture names where the backend used a different case. Components are pruned to what these paths transitively reference. Note: catalog-api/openapi.yaml does NOT follow this convention — it documents the backend paths and http://localhost:8000 as its server, so its operations cannot be called as written from the portal. Left alone here; worth aligning separately. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
customers-api
Kong routing/policy layer for the customers slice of
classic-models-api (see /Users/stephanetailland/git/classic-models-api),
split out per the DDD decomposition in ../kong-konnect-deployment-strategy.md.
The backend itself stays a single monolith — only Kong does the domain
split. Same role as ../catalog-api plays for catalog, structure
deliberately mirrored.
REST only for now (kong/rest/) — 8 routes covering
Customer plus its orders/payments sub-resources (cross-domain reads,
same backend). No MCP surface yet, unlike catalog-api — add one
(kong/mcp/, a mcp-customers Keycloak audience/client-scope, an entry in
dataplane-customers's JWT_AUDIENCE_WHITELIST) the same way if/when this
domain needs an MCP entry point.
| Route | Method | Backend path |
|---|---|---|
/customers/v1/customers/ |
GET, POST | /classic-models/api/v1/customers/ |
/customers/v1/customers/{customernumber}/ |
GET, PUT, PATCH, DELETE | /classic-models/api/v1/customers/{customernumber}/ |
/customers/v1/customers/{customernumber}/orders/ |
GET | /classic-models/api/v1/customers/{customernumber}/orders/ |
/customers/v1/customers/{customernumber}/payments/ |
GET | /classic-models/api/v1/customers/{customernumber}/payments/ |
Auth
openid-connect on the REST service, audience_required/token-exchange
target = classic-models-api (BACKEND_AUDIENCE). Unlike catalog-api,
there's no MCP hop minting an intermediate customers-api-audience token
today — a caller gets one directly via kong-token-exchange-broker
(customers-api-audience client scope, added there 2026-08-23) and calls
these routes with it; the REST-layer plugin then exchanges that token again
to classic-models-api before it reaches the backend, same second-hop
pattern as catalog-api's REST layer. IdP is the local Keycloak
(https://keycloak.sttlab.local/realms/classic-models) — see
../dataplane-customers/README.md and ../STATUS.md sections 15/16 for
why (platform-wide migration off the VPS Keycloak, not customers-specific).
consumer_claims/consumer_by map the JWT sub to a Kong Consumer for
per-consumer rate limiting, same as catalog-api.
Other policies
Per-consumer rate limiting, response caching (GET/HEAD), audit log
(http-log, endpoint still a placeholder — no real log collector in this
lab, same caveat as catalog-api).
Structure
Same three-piece dev/ layout as catalog-api: dev/gitrepository.yaml +
dev/flux-kustomization.yaml (deploys ./kong into the customers
namespace's dev environment, dependsOn dataplane-customers's Gateway
Kustomization), dev/externalsecret.yaml (git deploy key),
dev/token-exchange-broker-externalsecret.yaml (the broker's client
secret). kong/rest/ — service, routes, path-rewrites, auth/rate-
limit/cache/audit-log policies and their bindings.
Not deployed yet — blocked on one external step: the gitea repo
kong-customers-api.git this dev/gitrepository.yaml points at doesn't
exist (https://gitea.sttlab.eu/stt/kong-customers-api → 404 as of
2026-08-23). A dedicated deploy keypair was generated and stored in Vault
(kong-v2/customers-api/git-deploy-key) as if it did — once the repo
exists and that key is registered as its deploy key, this content needs to
be pushed to it, then dev/gitrepository.yaml + dev/flux-kustomization.yaml
- the two
dev/*externalsecret.yamlfiles applied to the cluster.kong-v2/customers-api/token-exchange-broker(the broker's client secret, copied from the live local Keycloak) is already stored in Vault and ready.