G3N Common Contract

Appearance

Client Shim (Thin) ​

This is a contract-only helper that normalizes the most common integration edges without becoming a full SDK. It does not add new endpoints or change the contract.

What it does

  • Normalizes header placement (x-session-guid, x-api-key, x-orgcode, x-cccode).
  • Enforces GET=query and POST=JSON body semantics.
  • Provides safe retry posture for idempotent calls.
  • Leaves 404 ambiguous (not found vs not associated) to align with anti-enumeration.

Downloads

Usage (Node.js)

js
const { requestJson, assertSuccess } = require('./client-shim-node');

const envelope = await requestJson({
  method: 'GET',
  path: '/pvm/variant/get',
  query: { variant_id: 'VAR123', style_id: 'STYLE123' },
  auth: { sessionGuid: process.env.SESSION_GUID, orgcode: 'ACME' },
});
const data = assertSuccess(envelope);

Request context object (Node.js)

js
const { requestJson } = require('./client-shim-node');

const context = {
  service: 'pvm',
  sessionGuid: process.env.SESSION_GUID,
  orgcode: 'ACME',
};

const envelope = await requestJson({
  method: 'GET',
  path: '/pvm/style/get',
  query: { style_id: 'STYLE123' },
  context,
});

USM body auth (Node.js)

js
const envelope = await requestJson({
  method: 'POST',
  path: '/usm/session/get',
  body: {},
  context: { service: 'usm', sessionGuid: 'SESSION' },
});

Usage (Python)

python
from client_shim_python import request_json, assert_success

envelope = request_json(
    method='POST',
    path='/ofm/org/get',
    body={ 'org_guid': 'ORG123' },
    auth={ 'session_guid': 'SESSION', 'orgcode': 'ACME' },
)
org = assert_success(envelope)

Notes

  • 404 is ambiguous: it can mean “not found” or “not associated.” Use /common/troubleshooting.html before assuming absence.
  • expected_revision must be supplied on updates for revisioned records (HTTP 428/409 on mismatch).
  • Retries should be reserved for idempotent calls unless an endpoint explicitly supports idempotency keys.
  • For USM session/API-key calls, use body auth (authInBody / auth_in_body) to include session_guid or api_key in the JSON body.