Developer Guide
JSON for API Development
Design JSON APIs with the right Content-Type, error objects, pagination, and ISO dates. Covers envelopes, null versus omit, and trailing commas in payloads.
A JSON API is a contract about bytes on the wire, not a dump of your ORM. Clients cache responses, generate types, and retry on 5xx. They cannot do any of that if Content-Type is wrong, if dates are timestamps in one route and strings in another, or if an error is sometimes a string and sometimes an object.
This is not a config-file guide. config.json is loaded by operators and validated with a schema at boot. An API payload is parsed thousands of times a second by strangers. The overlap is the grammar — double quotes, no trailing commas — and the tools: /tools/json-formatter for tree, sort, and line-column errors; /tools/json-editor for Ace editing; /tools/json-escape when a string needs to live inside JSON.
Content-Type and the body you actually sent
Successful JSON responses should use Content-Type: application/json (and charset=utf-8 if you set a charset at all). Do not send JSON with text/plain and hope JSON.parse still runs — some clients will not try. Empty 204 responses should have no body; a null body with 200 is a different, documented choice.
Request bodies need the same header. A server that accepts JSON but reads req.body as a form will see garbage. When a payload looks “fine in curl” and fails in the browser, pretty-print it in /tools/json-formatter and check that it is actually JSON, not a JavaScript object literal.
Envelope versus raw resources
Raw: {"id":"inv_9","total_cents":1200}. Envelope: {"data":{"id":"inv_9","total_cents":1200},"request_id":"r_1"}. Envelopes make it easy to add data, error, meta, and pagination without breaking field names on the resource. Raw is smaller and maps 1:1 to a type.
Pick one per API, not per endpoint. Mixing them forces every client to branch. If you already shipped raw objects, add fields to the object rather than wrapping it later — or version the path (/v2).
Error objects
Use a stable shape: HTTP status for the class of failure, and a JSON body with a machine code, a human message, and optional details (field, constraint). Example: {"error":{"code":"validation_error","message":"email is invalid","details":[{"field":"email"}]}}.
Do not return HTML error pages on /api/*. Do not return a bare string. Clients should be able to switch on code without scraping English. Keep message safe to show; put stack traces in server logs only.
Pagination, dates, null versus omit
Cursor or page+per_page both work; returning { "items": [...], "next_cursor": "abc" } is enough to document. Do not return one giant array and hope the dataset stays small.
Dates in JSON are strings. ISO-8601 in UTC (2023-11-14T22:13:20Z) is the interoperable choice. Unix seconds are fine if you document them as numbers and never mix in milliseconds. null means “the field exists and is empty.” Omitting the key means “not provided.” For PATCH, that distinction is the difference between clearing a title and leaving it alone.
Trailing commas and other grammar that is not JSON
Trailing commas, single-quoted keys, comments, and undefined are JavaScript. JSON.parse rejects them. /tools/json-formatter reports the line and column; /tools/json-editor flags invalid buffers on each keystroke but does not show line+column — that tree and those coordinates live on the formatter.
When a user-supplied string contains quotes or backslashes, escape it with /tools/json-escape rather than wrapping it in quotes by hand.
Common pitfalls
Returning 200 with {"success":false} hides failures from HTTP-aware clients and load balancers. Using floating-point for money hides rounding. Using local timezone strings without an offset hides the instant you meant.
Sorting keys in /tools/json-formatter is for humans and golden-file tests; it is not part of JSON equality in the spec. Pretty-print in development, minify on the wire if size matters, and keep a schema (OpenAPI, JSON Schema) so “optional” does not mean five incompatible omissions.
- Trailing commas are invalid JSON.
- Tree view is on
/tools/json-formatter, not/tools/json-editor. - Escape untrusted strings with
/tools/json-escapebefore they sit in a JSON value.
Worked examples
List response with a cursor
{
"items": [
{
"id": "inv_9",
"total_cents": 1200,
"created_at": "2023-11-14T22:13:20Z"
}
],
"next_cursor": "inv_8"
}created_at is ISO-8601 UTC, the same instant as Unix 1700000000. Paste into /tools/json-formatter and switch to the tree to fold items.
Trailing comma (invalid)
{
"id": "inv_9",
}Error at the closing brace — trailing commas are not JSON.The formatter gives a line and column. Remove the comma after the last property, or the parse will keep failing.
Frequently asked questions
Should every response wrap data in { "data": ... }?
Only if you committed to an envelope. Consistency matters more than which style you picked. Do not wrap errors one way and successes another without documenting it.
How should I send a date?
A UTC ISO-8601 string is the default. If you send Unix seconds, document that they are seconds, not Date.now() milliseconds.
Why does my JSON work in the editor but fail in production?
The editor and formatter both use JSON.parse. Production failures are usually a different body (HTML, a BOM, concatenated logs) or a Content-Type the client refused to parse.
Where do I pretty-print an API payload?
/tools/json-formatter formats, minifies, validates, sorts keys, and shows a collapsible tree. /tools/json-editor is Ace with fold and format — not a data tree.
Summary
Treat JSON as a public contract: honest Content-Type, one error shape, documented pagination, ISO dates, and a clear null versus omit rule. Validate payloads in /tools/json-formatter, edit them in /tools/json-editor, and escape messy strings in /tools/json-escape before they reach the wire.