G3N Common Contract

Appearance

Common Contract ​

This page captures the shared contract for all g3nretailstack services. It describes what callers see: surface types, request/response envelopes, auth/context expectations, pagination, errors, and build metadata. Internal infrastructure, storage, and wiring stay out of scope.

For the service-by-service narrative, see /story/.

Quick links

Guides ​

Reference ​

Operations ​

Surface catalog ​

  • Public API (API Gateway) — JSON over HTTPS on custom domains (e.g., https://api.g3nretailstack.com/<service>/...). Use for client/partner integrations. Prefer the custom domain over execute-api URLs.
  • Direct Lambda actions — JSON invoke payloads for operational use and CLI/SDKs. Names are listed per service.
  • CLI — In-repo g3n commands that call the same APIs/Lambdas. --profile is required; --region optional. Use --base-url to override the default custom domain if needed.
  • Downstream surfaces — Some services emit/consume events or files (e.g., EventBridge, SQS, S3). Where present, each service page lists schemas, when events fire, and how to consume or upload.
  • MCP — MCP protocol at https://api.mcp.g3nretailstack.com/mcp with static protocol docs on https://mcp.g3nretailstack.com. Content stays contract-only.

Envelope, stats, and telemetry ​

  • Responses share the envelope { success, data?, error?, stats?, revision? }.
  • stats.build includes build_major, build_minor, and build_id (e.g., MONDAY-1765671116). Every page footer shows the build plus a UTC timestamp for when the docs were generated.
  • npm run publish:content uses one shared build tuple (BUILD_MAJOR, BUILD_MINOR, BUILD_TIMESTAMP) for the entire docs build so generated pages are timestamped atomically per publish run.
  • stats is returned on successful calls and often on errors: call, service, request_id, timestamp_utc, latency_ms, optional bandwidth counters, and passthrough context when provided (for example actor, orgcode, cccode). Bearer session_guid values are not returned in stats.
  • revision is an opaque per-record revision GUID (when a single stateful record is returned). Update-like operations can use it for optimistic concurrency.

Auth and context ​

  • Protected API Gateway surfaces require a valid USM session_guid (the session identifier) and reject when missing/invalid/expired. Only explicitly public endpoints skip this (e.g., UAS /stat, invitation create/doom Lambdas).
  • Direct Lambda actions may be unauthenticated unless the service states otherwise; they can still accept actor for audit, and some accept orgcode/cccode as opaque passthrough for correlation.
  • Optional cost attribution: callers can provide a cost centre code via cccode (request field) and/or header x-cccode. Format is ^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$ and values are canonicalized to uppercase. When both are provided they must match; invalid values return HTTP 400. Exception: OFM uses cccode as a domain identifier (cost centre records), so x-cccode is telemetry-only and is parsed as cccode_attrib (no equality enforcement with domain cccode).
  • session_guid is required and validated on protected surfaces; it is treated as a secret bearer token and is not emitted in response stats or tenant events/audits.
  • If both session_guid and api_key are provided, the session is authoritative and the API key is ignored.
  • For user-facing flows, create/validate sessions via USM, then call downstream services with session_guid where auth is required.

Field placement (headers vs query vs body) ​

  • GET endpoints take inputs as query parameters and auth/tenancy as headers. Do not send JSON bodies on GET.
  • POST endpoints take inputs as JSON bodies; auth uses headers (x-session-guid or x-api-key) as the canonical pattern. Some services accept body auth for compatibility.
  • Some read/list/resolve endpoints are POST by design. Use the method documented on the service page, and see /common/http-methods.html for a rule-of-thumb.
  • When a doc shows a JSON-shaped request under a GET endpoint, treat it as query parameters; curl examples on each service page show the canonical placement.

Pagination ​

  • List endpoints default to limit 8 and clamp 1–256 inclusive.
  • next_token (opaque base64/JSON per service) is returned when more data exists and must be echoed back verbatim to continue.
  • CLI surfaces expose pagination flags; service pages show examples for both API and CLI.
  • High-cardinality lists require a scoping filter (parent id, status, facility, or channel); if not documented, expect tightening before production.
  • Stable sort order is defined per endpoint; do not assume ordering beyond what a service documents.

Errors (contract) ​

  • Errors use error.major/error.minor tags with en_US messages and optional details JSON. Payloads redact secrets.
  • HTTP guidance: validation → 400, auth/session → 401, forbidden/state/ownership → 403, not found → 404, conflict/limits → 409/429, gone/expired → 410, server issues → 500.
  • Service pages enumerate their specific tags and list what is accepted/rejected for each operation.
  • Anti-enumeration: some org-scoped services return 404 not-found when the caller is not associated with the org (even if the org exists). See /common/troubleshooting.html for details and a checklist.

Optimistic concurrency (revisioned records) ​

  • Mutations that update an existing revisioned record must include expected_revision. Missing → expected-revision-required (HTTP 428). Mismatch → conflict (HTTP 409) and the failure payload includes the current record snapshot + current revision (see error.details.{provided_revision,current_revision,current_record}).

Usage patterns and best practices ​

  • Prefer the custom domain (api.g3nretailstack.com) for all HTTP calls; avoid execute-api URLs.
  • Always pass --profile to CLI (required) and --region if not set in the profile.
  • For authenticated flows: obtain a USM session, forward session_guid to downstream services that need auth, and include actor when tracking who triggered the call.
  • Respect pagination defaults; do not assume stable ordering beyond what each service documents.
  • Use examples on each service page as templates: they show required/optional fields, best-practice usage, and representative errors.

MCP (contract-only) ​

  • MCP server: https://api.mcp.g3nretailstack.com/mcp (CloudFront mcp.g3nretailstack.com/mcp redirects here).
  • Protocol docs: https://mcp.g3nretailstack.com/<service>/PROTOCOL.md (mirrored to doc.g3nretailstack.com/<service>/PROTOCOL.md for convenience).
  • MCP content mirrors the HTTP/Lambda contract only; no internal details or infrastructure specifics appear in public MCP docs.