# JSON bodies

`Bond.json_body(conn, User.codec)` decodes the body of the request into a struct, as a `Result[User]`. A body that does not fit is an error that makes a 400, so `try` it and the handler needs no more code. Always `try` it (or match the `Result`): a handler that drops the `Result` goes on as if the body were fine and accepts the request.

The request must have exactly one `Content-Type`, and it must say it is JSON: `application/json`, or a `type/name+json` such as `application/vnd.api+json`, with any parameters (`; charset=utf-8`) and in any case. A missing, repeated or other content type is a 400 with the body `content type must be application/json`, and an empty body is a 400 with `the body is empty`. The body is read as UTF-8 whatever the charset parameter says.

A body that is not one JSON document that fits the struct is a 400 with `invalid body: ` and what is wrong, such as `age: expected required field`. Extra keys are ignored. The message names the struct field and never repeats the text the client sent: the path of the codec stops at its first `[`, so an error inside a map or a list says `scores: ...` or `tags: ...`, and not the key or the index. The size of the body is limited by the server: a body over `max_body_bytes` is a 413 and never reaches the app (see [Running and options](https://www.agentica-lang.com/bond/guide/server/index.md)).

```agentica
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

struct NewUser
  name: String
  age: Int
end

def create_user(conn: Bond.Conn) -> Result[Bond.Conn]
  user = try Bond.json_body(conn, NewUser.codec)
  return ok(Bond.text(conn, 201, "hello #{user.name}, #{user.age}"))
end

def post(app: Bond.App, type: String, body: String) -> Void
  headers = [HTTP.Header(name: "Content-Type", value: type)]
  response = Testing.request(app, "POST", "/users", headers, body)
  puts("#{response.status} #{Testing.text(response).unwrap!}")
end

def main() -> Void
  app = Bond.app() |> Bond.post("/users", &create_user)
  post(app, "application/json", "{\"name\": \"Ana\", \"age\": 30}")
  post(app, "text/plain", "{\"name\": \"Ana\", \"age\": 30}")
  post(app, "application/json", "")
  post(app, "application/json", "{\"name\": \"Ana\"")
  post(app, "application/json", "{\"name\": \"Ana\"}")
  post(app, "application/json", "{\"name\": \"Ana\", \"age\": \"thirty\"}")
end
```

```output
201 hello Ana, 30
400 content type must be application/json
400 the body is empty
400 invalid body: invalid JSON
400 invalid body: age: expected required field
400 invalid body: age: expected signed 64-bit Int
```

## Answering with JSON

`Bond.json_as(conn, status, User.codec, user)` answers a struct as JSON and encodes it once, with `Content-Type: application/json`. Bond takes the codec, as `json_body` does, because a function of your own that is generic over `T` cannot call `JSON.encode` on `T`.

`Bond.json(conn, status, value)` takes a `JSON.Value`, which is the way for a list or a map (`JSON.from(scores)`), since a codec is for a struct.

```agentica
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

struct User
  name: String
  age: Int
end

def show_user(conn: Bond.Conn) -> Result[Bond.Conn]
  return ok(Bond.json_as(conn, 200, User.codec, User(name: "Ana", age: 30)))
end

def show_ages(conn: Bond.Conn) -> Result[Bond.Conn]
  return ok(Bond.json(conn, 200, JSON.from({"ana": 30, "luis": 25})))
end

def main() -> Void
  app = (
    Bond.app()
    |> Bond.get("/user", &show_user)
    |> Bond.get("/ages", &show_ages)
  )
  for path in ["/user", "/ages"]
    response = Testing.request(app, "GET", path)
    puts("#{response.status} #{Testing.text(response).unwrap!}")
  end
end
```

```output
200 {"name":"Ana","age":30}
200 {"ana":30,"luis":25}
```
