handle formats

README.md

@@ -42,7 +42,7 @@ docker run --rm -p 3000:3000 tbd
 |--------|------|-------------|
 | `GET` | `/` | The UI: an HTML shell that loads the compiled ClojureScript from `/js/main.js` |
 | `GET` | `/api/ping` | Health check, returns `pong` |
-| `GET` | `/api/add?x=2&y=3` | Adds two numbers, returns EDN: `{:result 5}` (400 if either is missing or not a number) |
+| `GET` | `/api/add?x=2&y=3` | Adds two numbers: `{:result 5}` (EDN by default, see [Formats](#formats)) (400 if either is missing or not a number) |
 | `GET` | `/api-docs` | Swagger UI |
 | `GET` | `/swagger.json` | OpenAPI/Swagger spec |
 | `GET` | `/auth/login` | Starts the Gitea OAuth login (redirects to Gitea) |
@@ -60,8 +60,20 @@ docker run --rm -p 3000:3000 tbd
 ```bash
 curl localhost:3000/api/ping           # pong
 curl 'localhost:3000/api/add?x=2&y=3'  # {:result 5}
+curl 'localhost:3000/api/add?x=2&y=3' -H 'Accept: application/json'  # {"result":5}
 ```
 
+## Formats
+
+The API speaks EDN, JSON and Transit (`application/transit+json`, `application/transit+msgpack`).
+Responses follow the request's `Accept` header, and request bodies are read by their `Content-Type`.
+**EDN is the default**: with no `Accept` (or `*/*`, or a type the API can't produce) you get EDN, and a
+body sent with no `Content-Type` is read as EDN. Errors (400, 401, 403, ...) use the same format
+as everything else. Two exceptions: `/api/ping` is always `text/plain`, and `/swagger.json` is always JSON.
+
+Handlers return plain data (`(tbd.http/respond 200 {:result 5})`), and the muuntaja middleware in
+`tbd.core` encodes it; don't `pr-str` a body yourself.
+
 ## Todos
 
 Each logged-in user has their own todo list, keyed by their Gitea user id. Every query is