Typed Persona REST Adapter and JSON:API Envelope
Overview
Keep transport, Persona resource envelopes, and domain decisions separate. The adapter should preserve raw identifiers and metadata, tolerate new resources and fields, and expose explicit mutation evidence rather than flattening every response into a brittle model.
Prerequisites
- Endpoint inventory and approved API version
- Language runtime with HTTP, JSON, and constant-time comparison support
- Domain boundary defining what may contain PII
Instructions
Step 1: Define the transport core
Centralize the API base, bearer header, dated version, timeouts, request IDs, and safe telemetry. Do not retry mutations blindly.
Step 2: Model JSON:API generically
Represent data, type, id, attributes, relationships, included, meta, links, and structured errors before adding endpoint-specific views.
Step 3: Preserve compatible additions
Treat unknown fields, resource types, event types, and array order changes as data to preserve or ignore safely, not parse failures.
Step 4: Separate command from query
Require an operation ID and Idempotency-Key for POST commands. Queries may use bounded retries; commands reconcile observed state after ambiguity.
Step 5: Normalize evidence, not identity
Return status, request ID, rate and quota headers, resource ID, and a redacted envelope hash. Keep customer attributes behind the domain privacy boundary.
Step 6: Test with contract fixtures
Cover errors, pagination, unknown fields, multiple verification types, session metadata, throttling, and ambiguous POST outcomes.
Authentication
Inject the environment-scoped bearer key at the transport boundary and pin Persona-Version per request. Callers must never pass raw credentials or select an arbitrary host.
Tool Discipline
Use Read and Grep to inspect application configuration, provider documentation, fixtures, schemas, tests, and redacted operational evidence before proposing a change. Use Write or Edit only for an approved implementation, configuration, test, runbook, or redacted receipt. Do not create, resume, approve, decline, redact, rotate, revoke, deploy, or otherwise mutate production Persona resources without explicit operator approval.
Output
- Typed transport and JSON:API envelope interfaces
- Mutation command and read-query contracts
- Compatibility and redaction test matrix
Return the environment, resource and event identifiers, API version, template context, source-contract fingerprint, evidence, unresolved risk, rollback state, and final decision without exposing bearer keys, webhook secrets, inquiry session tokens, raw identity documents, or unnecessary PII.
Examples
A TypeScript adapter returns PersonaEnvelope<Inquiry> plus a redacted request receipt. An unknown relationship is retained in the raw envelope while the domain mapper continues using the fields it understands.
Error Handling
| Failure | Response |
|---|---|
| Unknown type or field | Preserve or ignore it safely and surface a compatibility metric; do not reject a compatible API addition. |
| Timeout after POST | Read the resource or operation evidence before considering a replay with the same parameters. |
| Malformed error envelope | Return transport status and a redacted body hash while protecting PII. |
Validation
Verify the result against the linked first-party evidence, the pinned API version, redacted contract fixtures, an expected failure path, and the documented rollback or manual-disposition path. A successful request is not proof of a successful identity decision.