API prompts: document the full operation matrix

Last updated: 2 Oct 202611 min read

tutorial

An API operation page should describe how a caller forms a request and interprets every documented outcome. The prompt must enumerate method, path parameters, authentication scope, successful response shape, material error codes, and retry guidance supported by the service contract. A happy-path body alone leaves integrators to guess what happens when an ID is missing or access is denied. The prompt should label fields that are required, optional, or conditionally present and keep null distinct from absent. If the source packet does not establish an error code or retry policy, mark it for owner review instead of filling the gap with a familiar convention.

Operational case

For GET /v2/shipments/{shipmentId}, the approved contract requires shipmentId and a reader permission. The successful response has shipment_id and status; the held fixture uses SH-4721 and status held. A not-found result is documented as 404 with a structured code. The security test proves a caller without the reader permission receives 403. The prompt leaves a timeout retry rule open until the API owner confirms it. It does not show a 200 response with status delivered for a missing ID, and it does not treat 403 as evidence that the shipment does not exist.

GET /v2/shipments/{shipmentId}
Required path: shipmentId; permission: shipment:read.
200: shipment_id, status; held fixture SH-4721.
403: caller lacks read permission.
404: shipment ID not found under approved visibility rule.
Retry on timeout: unresolved until owner confirms policy.

Performance and operating cost

For R response classes and F documented fields, a complete review is O(R+F) contract checks per operation. Authentication and error tests often cost more to inspect than the success fixture, but they prevent misleading integration instructions. A generated error matrix should be checked against actual tests or approved specification, not merely against another generated page. Omitting unknown retry behavior can be safer than prescribing retries that amplify an outage or duplicate a side effect.

Common Mistakes

Do not infer 404 versus 403 behavior without checking visibility rules.
Do not call an optional field required because it appears in one fixture.
Do not invent retry advice from a status code alone.

Connected lessons

prompt engineering

api documentation