API examples: validate payloads and strip credentials

Last updated: 7 Oct 202611 min read

tutorial

A documentation example should be a verified contract case, not a plausible-looking JSON object. The prompt must identify the fixture or test that supplies each field, use fictional identifiers, and omit live credentials and personal data. Validate the example against the released schema, then run a request or contract test in a safe environment where practical. Check that printed output agrees with the status description and version. For a request requiring authorization, use a clear placeholder rather than a valid token. The review should catch accidental copy of production IDs, access keys, internal hostnames, and sample values that imply a field exists when it does not.

Operational case

The held-shipment page includes SH-4721 as a fictional ID. Its 200 response shows shipment_id and status held, matching the approved fixture. An earlier draft inserted hold_reason and a long authorization token copied from a debug log; both are removed. The contract does not expose hold_reason, and the token is not safe to publish. The reviewer runs the example against a local fixture and confirms the JSON parses and the two public fields have the right types. A 403 example uses a fabricated error code already present in the permission test, not a copied customer response.

Request ID: SH-4721 (fictional fixture).
200 JSON: {"shipment_id":"SH-4721","status":"held"}
Authorization: <reader-token> placeholder only.
Reject: internal hold_reason, live token, production identifier.
Check: JSON parse, released schema, fixture output, version.

Performance and operating cost

Parsing an example of B bytes is O(B) and schema validation depends on the schema depth and field count; a single local fixture run is usually cheap compared with a published integration error. Secret scanning adds a pass over the draft and generated files. The prompt should not claim that one valid example proves the whole operation correct; negative cases and permission boundaries need separate tests. Keep examples few and distinct so each teaches a meaningful branch rather than repeating the success body with new IDs.

Common Mistakes

Do not publish a real token as a convenient example.
Do not add a field because it appears in an internal log.
Do not trust syntax-only JSON validation as proof of contract alignment.

Connected lessons

prompt engineering

api documentation