Clarify the task and decision
This guide turns api quickstart into a reviewable operating workflow. It connects domain decisions, ownership, evidence, and acceptance so the result continues to work in production.
Start with one authenticated request, validate the response contract, and add failure handling before connecting the CMS.
Practical workflow
- 1
Inventory source types, identifiers, fields, locales, owners, and publication states.
- 2
Choose the delivery pattern from volume, latency, editorial control, and failure tolerance.
- 3
Map the source record to a separate language-version record with durable linkage.
- 4
Add authentication, idempotency, retry, cache invalidation, logging, and access controls.
- 5
Test publication, source changes, unavailable results, rollback, keyboard operation, and monitoring before release.
Worked example or tool
A complete request and response pair includes authentication, locale, mode, idempotency, and error handling. In the tool, also record the baseline, owner, decision, evidence, open issue, and approval date. Use a real page or transaction so the team sees dependencies, exceptions, and the maintenance work that follows release.
| Decision point | Record | Acceptance criterion |
|---|---|---|
| Baseline | Observed current state | Source and date recorded |
| Decision | Selected option and rationale | Risk and audience considered |
| Evidence | Test, document, or measure | Reviewable and version-specific |
| Approval | Name, role, and date | All mandatory criteria met |
Send one production-shaped request
Create a server-side integration client and store its credential in the deployment secret manager. Send UTF-8 JSON over HTTPS with a stable source identifier, source revision, requested locale, language mode, and content body. Add an idempotency key that remains the same when the identical job is retried. Do not expose credentials in browser code, repository files, CMS fields, screenshots, or client-visible error responses.
Start with a representative but non-sensitive service page. Include headings, lists, links, and a legal or operational condition so the response exercises the real content contract. Reject an empty source identifier, unsupported locale, unknown mode, oversized body, or malformed structure before calling the API. Set an explicit connection and response timeout and propagate a correlation identifier into your application logs.
| Request field | Purpose | Validation |
|---|---|---|
| sourceId | Durable link to the CMS record | Required, stable, non-personal |
| sourceRevision | Detects stale results | Required and immutable for the request |
| locale and mode | Selects language rules | Must be an enabled combination |
| idempotencyKey | Makes retries safe | Same operation uses the same key |
Validate the complete response contract
Treat a successful HTTP status as only the first check. Validate the response schema, result identifier, source identifier and revision, locale, language mode, processing status, content blocks, warnings, and model or ruleset version where supplied. Unknown enum values and missing required fields should fail closed into a reviewable integration error. Preserve warnings beside the draft because they can identify terminology, source quality, or manual-review requirements.
Store generated output as a separate draft revision rather than overwriting the approved source. Record request and result identifiers, transformation settings, timestamps, and an integrity hash of the source revision. Render a diff for reviewers and escape all output according to its destination. Generated markup is untrusted input until schema validation, sanitisation, accessibility checks, and human approval are complete.
- 1
Validate the outbound payload against a local schema.
- 2
Send the request with authentication, timeout, idempotency, and correlation headers.
- 3
Validate status, headers, and response body against the pinned contract.
- 4
Create a separate CMS draft linked to the exact source revision.
- 5
Route warnings and diffs into the correct editorial review queue.
Handle errors without duplicating or losing work
Retry timeouts, connection failures, and rate limits only when the operation is idempotent. Use capped exponential backoff with jitter and respect a server-provided retry delay. Do not retry validation failures, authentication failures, or unsupported options until configuration changes. Place exhausted operations in a dead-letter queue with the source reference, safe error category, attempt count, and next responsible team.
Separate user-facing state from diagnostic detail. Editors need clear states such as queued, processing, draft ready, action required, and failed with a safe next step. Operations need request identifiers, duration, status category, and retry history, but not the full source text in ordinary logs. Alert on sustained error rate, growing queue age, authentication failures, schema mismatches, and drafts whose source revision changed during processing.
Every retryable operation has a stable idempotency key.
Backoff is capped and honours rate-limit instructions.
Logs exclude credentials and unnecessary content bodies.
Dead-letter items have an owner and replay procedure.
A stale result cannot silently replace a newer source revision.
Prove the integration before release
Test valid requests, every documented validation error, expired and revoked credentials, timeouts, rate limits, duplicate submission, out-of-order completion, schema evolution, sanitisation, and source changes during processing. Confirm that monitoring identifies each failure and that a trained operator can replay or close the item without database editing. Run accessibility and editorial review on the rendered draft rather than only the raw response.
Release with a restricted credential, defined rate and spend limits, dashboards, alert ownership, and a rollback switch that stops new generation without affecting published content. Pin the supported contract version and schedule an upgrade review. The production acceptance record should include test evidence, security approval, data-flow documentation, reviewer sign-off, operating instructions, and the successful restoration of one deliberately failed job.
Roles, evidence, and approval
Keep generation separate from publication. A successful response is a draft, not an approval. Store the source identifier and version, transformation settings, result identifier, review state, approver, and publication time. When the source changes, mark the language version for review instead of silently replacing approved content. This makes rollback and audit possible across platforms.
Operations and maintenance
The work does not end at publication. Link the language version or configuration to its source, monitor quality and service measures, and define concrete review triggers. Triggers include source changes, legal changes, new audience needs, recurring support questions, technical changes, and incidents. A named owner evaluates the trigger, opens a new revision when needed, and records renewed approval.
Release checklist
The integration uses durable source identifiers.
Credentials are stored server-side and rotated.
Timeout, retry, and rate-limit behavior are defined.
Repeated requests are idempotent.
Generated content enters a review state.
Source changes invalidate or reopen the version.
Language navigation works by keyboard and assistive technology.
Monitoring covers failures, queues, latency, and stale content.