Agent WranglersRequests and responses
Send JSON with one naming style, exact dates, safe money values and string IDs, so every field means the same thing everywhere in the API.
- Required 6
- Recommended 2
Required
Use JSON with one naming style
RequiredSend and accept JSON with
Content-Type: application/json, and name every field in one style across the whole API.Send dates as RFC 3339 with a time zone
RequiredWrite every moment in time as an RFC 3339 string with a zone or offset. Write a calendar date with no time as
YYYY-MM-DD.Send money as an integer with its currency
RequiredSend amounts as an integer count of the currency's smallest unit, together with the ISO 4217 currency code. Never use floating-point numbers for money.
Send IDs as strings
RequiredType every ID as a string, even when it looks like a number today.
Give every response one shape
RequiredReturn the same fields of the same types every time, and describe them in the contract. Leave out a field only when the contract says it is optional.
Accept only fields you know
RequiredValidate every request body against its schema at the edge. Reject unknown fields and wrong types with a clear error.
Recommended
Use enums for fixed values
RecommendedGive every field with a fixed set of values an enum in the contract, and document what each value means.
Say which format PATCH accepts
RecommendedAccept PATCH bodies in one documented patch format, and name it in the
Content-Typeheader.
For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/requests-and-responses.