---
title: "Requests and responses · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/requests-and-responses
updated: 2026-10-20
licence: "All rights reserved"
---

# Requests and responses

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> 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.

**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`.

## Required

- [Use JSON with one naming style](https://agentwranglers.se/playbook/api-design/requests-and-responses/json-conventions): Send 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](https://agentwranglers.se/playbook/api-design/requests-and-responses/dates-and-times): Write 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](https://agentwranglers.se/playbook/api-design/requests-and-responses/money): Send 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](https://agentwranglers.se/playbook/api-design/requests-and-responses/string-ids): Type every ID as a string, even when it looks like a number today.
- [Give every response one shape](https://agentwranglers.se/playbook/api-design/requests-and-responses/response-shape): Return 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](https://agentwranglers.se/playbook/api-design/requests-and-responses/strict-input): Validate every request body, query parameter and path parameter against its schema at the edge. Reject unknown fields and wrong types with a clear error.
- [Set caching headers on every response](https://agentwranglers.se/playbook/api-design/requests-and-responses/api-cache-headers): Send an explicit `Cache-Control` header on every API response. Send `no-store` on any response with personal or account data.

## Recommended

- [Use enums for fixed values](https://agentwranglers.se/playbook/api-design/requests-and-responses/api-enums): Give every field with a fixed set of values an enum in the contract, and document what each value means.
- [Say which format PATCH accepts](https://agentwranglers.se/playbook/api-design/requests-and-responses/patch-format): Accept PATCH bodies in one documented patch format, and name it in the `Content-Type` header.

- Previous: [Resources and methods](https://agentwranglers.se/playbook/api-design/resources-and-methods)
- Next: [Errors](https://agentwranglers.se/playbook/api-design/errors)
- [All chapters](https://agentwranglers.se/playbook/api-design)