API Schema — Resource Map — Architecture Documentation

API Schema — Resource Map

The REST surface grouped by owning service: gateway auth/account, store catalog + CMS, commerce orders/returns, and backend's internal-only resources.

Diagram v1.3 · Updated 04 Aug 2026, 08:10 GST— Path scheme, auth rules and response envelope documented per owning service.

Prev Next

100%

Rendering diagram…

Scroll to zoom · drag to pan

1 · Step-by-step workflow

Client obtains a token

POST /api/authenticate, or Google OAuth2 at /oauth2/authorization/google.
The gateway is the only issuer of the platform JWT.

Client calls a versioned path

/api/v1/** is the single public versioned surface, reachable only through the gateway.
/api/* without a version is auth/account boilerplate on the gateway.

Gateway authorises the route

permitAll for catalog reads, /coupons/validate, /orders/track/{orderNumber} and registration flows.
authenticated for /account/profile, orders, payments and order-returns.
ROLE_ADMIN for /api/v1/admin/**, /api/admin/users, /authorities and /gateway/routes.

Owning service handles the resource

Store fronts catalog, CMS and admin; commerce fronts orders, profile, coupons and returns.
/api/v1/admin/ledgerly/** is routed straight through to backend.

Core answers over the internal surface

/internal/v1/** executes the business logic and reads or writes miniandmore.

Response is enveloped

ApiResponse<T>: { success, data, meta: { requestId, timestamp } }.

2 · Additional details

Path scheme

/api/* — gateway auth, account and user administration.
/api/v1/** — public versioned catalog and commerce API via store/commerce.
/internal/v1/** — backend only, never proxied publicly.
/api/v1/admin/ledgerly/** — the one admin path served by backend itself.

Payload conventions

Catalog and CMS DTOs use camelCase.
Hand-built order, account and return endpoints use snake_case keys (full_name, order_number, product_id).

Documentation coverage

springdoc-openapi runs on gateway and backend only.
No single spec currently covers the full proxied surface.

Known gaps

There is no server-side cart API; checkout posts the full item list to POST /orders.
InternalStorageUploadResource has no @PreAuthorize of its own.
The Ledgerly webhook path has no committed proxy configuration.

3 · Advantages & usage

Advantage

Breaking changes ship as /api/v2 without disturbing existing clients.
Unversioned auth boilerplate stays clearly separated.

Usage

The web app and mobile clients only ever call /api/v1/** plus gateway auth paths.

4 · Phase 2 additions

Unified OpenAPI specification

Publish one spec covering the full proxied surface and generate clients from it.

Payload casing convergence

Normalise the snake_case order/account endpoints onto camelCase with a deprecation window.

Server-side cart API

Persist carts server-side instead of posting the full item list at checkout.