Protocols

When a client sends a request, the server needs to agree on how to encode the data. Katman handles this automatically through content negotiation — the client says what format it wants via the Accept header, and the server responds accordingly. No configuration needed.

The three formats

JSON is the default. Every client and every tool understands it. If you don't configure anything, this is what you get.

MessagePack is a binary format. Same data, fewer bytes. If you're building a mobile app or sending large payloads, switching to MessagePack can noticeably reduce bandwidth and improve parse speed.

devalue preserves JavaScript types that JSON loses. If your API returns Date objects, Map, Set, or BigInt, devalue keeps them intact instead of converting them to strings or empty objects.

How content negotiation works

The client sends an Accept header, and the server picks the matching format:

Accept: application/json              --> JSON (default)
Accept: application/x-msgpack         --> MessagePack
Accept: application/x-devalue+json    --> devalue

For request bodies, the server checks Content-Type and decodes accordingly. This all happens inside Katman — you don't need to configure anything on the server.

On the client side, setting binary: true in createLink switches to MessagePack automatically:

import { createLink } from "katman/client/ofetch"

const link = createLink({
  url: "http://localhost:3000",
  binary: true, // uses MessagePack for all requests
})

Choose a format

Most applications work great with plain JSON. Consider switching when:

• You need smaller payloads (mobile, IoT, high-traffic) --> MessagePack
• Your API returns Date, Map, Set, or BigInt --> devalue
• You want the lowest possible latency for repeated calls --> WebSocket