The API response format decides how a client reads the answer. A terminal user wants a single line. An application wants a structure it can parse. Both are reasonable, and the same endpoint can serve both if the client asks for the format it needs. The trouble starts when the default changes between endpoints or when the body says one thing and the Content-Type says another.
Our API collection uses a format parameter where it makes sense. The default is chosen per endpoint. Public IP address returns plain text by default because the common case is a shell call. IP Geolocation also defaults to plain text and switches to JSON with format=json. The email checker defaults to JSON because the answer has several fields.
Keep the API response format honest
An API response format that serves JSON as text/plain breaks clients that trust the header. A plain string served as application/json breaks parsers. The endpoint should set the header to match the body. When the format is JSON, send application/json. When it is text, send text/plain. When it is an image, send image/png.
curl "https://api2.globus.studio/v2/ip?format=json"
curl "https://api2.globus.studio/v2/ip?format=text"
curl "https://api2.globus.studio/v2/geo?ip=8.8.8.8&format=json"Use the format the client needs
A shell script can read a single value without a parser. A mobile app should ask for JSON and keep the fields it needs. A browser example can use JSONP when the endpoint supports it, though a normal fetch with CORS is the better default today.
A consistent API response format saves the client from guessing. Document the default on the API page and in the examples. If a client needs a different format, it should pass the parameter explicitly. That makes the request readable and the response predictable.
Do not change the default quietly
Changing the default API response format is a breaking change even if the endpoint accepts a parameter. Clients that never passed it will see a different body. If a new default is necessary, add a new endpoint or a version. Keep the old behaviour long enough for clients to move.
We keep response shapes stable for the same reason. New fields can appear in JSON. Existing fields keep their names and types. A client that ignores unknown fields keeps working.
Images and binary responses
Not every endpoint returns text. Image placeholder and QR generator return PNG. Their content type is part of the contract. A client that expects JSON should not call them without handling binary data.
The format parameter is a small feature. It is also the first place where a client notices inconsistency. Pick a default, document it and keep the header and the body in agreement.
Content negotiation and query parameters
HTTP has an Accept header for content negotiation. A public API can support it, but a query parameter is easier to see in a URL, a log and a support ticket. We use format for that reason. The header still matters for proxies and caches, so the response should set the correct content type either way.
Testing both paths
Test the API response format on both paths: the default and the explicit value. A client that asks for JSON should get JSON even when the default is text. A client that asks for text should get a body without braces. A quick check with curl -i shows the header and the first line of the body together.
curl -i "https://api2.globus.studio/v2/ip"
curl -i "https://api2.globus.studio/v2/ip?format=json"Read the IP endpoint page for the defaults and examples.
A simple rule for new endpoints: choose the API response format that the most common client needs, document it, and keep it for the life of the endpoint. A format parameter is a convenience, not a reason to change the contract later.
Further reading: RFC 8259, JSON.