Working With JSON

Why JSON won

JSON — JavaScript Object Notation — is the default data format for REST APIs because it strikes a rare balance: humans can read it at a glance, and every mainstream language can parse it with a single function call. It is lighter and less ceremonious than XML, and it maps cleanly onto the objects and arrays that programmers already work with every day.

A JSON document is built from just six value types: strings, numbers, booleans, null, arrays, and objects. Objects are unordered collections of key-value pairs; arrays are ordered lists of values. That deliberately small vocabulary is enough to describe almost any data an API needs to exchange, which is part of why JSON spread so quickly and now feels like the natural default rather than a choice you have to justify.

Parsing and serialising

Turning an in-memory object into a JSON string is serialising; turning a string back into objects is parsing. Nearly every language ships this functionality out of the box — for example JSON.parse and JSON.stringify in JavaScript, or the json module in Python — so you rarely write it yourself.

{
  "id": "case_001",
  "amount": 1499.50,
  "open": true,
  "tags": ["overdue", "priority"]
}

Always wrap parsing in error handling, though. A truncated response, a gateway timeout page, or an unexpected error document will not parse as valid JSON, and you want a clear, caught failure at that boundary rather than an exception thrown deep inside your business logic where the real cause is much harder to spot.

The number trap

JSON has a single numeric type, and many parsers map it straight onto a floating-point value. That is perfectly fine for most figures but genuinely dangerous for very large integers and for money. A 64-bit identifier can quietly lose precision when read as a float, silently corrupting the value so that two distinct records appear to share an id.

The usual fixes are well established: transmit large IDs as strings, and represent currency as integer minor units — cents rather than dollars — or as a decimal string that never goes through a float at all. When you build requests of your own, mirror whatever the API documents so that values survive the full round trip intact in both directions. Getting this wrong is subtle precisely because small numbers work fine and only large ones break.

Nulls, dates, and missing keys

JSON has no native date type, so timestamps travel as strings — almost always ISO 8601, such as 2026-06-29T03:15:00Z with an explicit time zone. Parse these into proper date objects in your language rather than comparing them as raw text, which can disagree with what you expect across offsets.

Be deliberate about absence, too, because JSON distinguishes two kinds of it. A key set to null is present but carries no value; a key that is simply missing from the object is a different thing again. Some APIs treat the two distinctly in PATCH bodies — null to clear a field, omitted to leave it untouched — so check the contract before assuming they are interchangeable, or you may clear data you meant to keep.

Sending JSON correctly

When you send a JSON body, set Content-Type: application/json on the request and ask for Accept: application/json in the reply, so both sides agree explicitly on the format. Forgetting these headers is a surprisingly common cause of mysterious 400 or 415 errors that have nothing to do with the data itself.

It is worth getting these two headers right reflexively on every call, since the failure they cause looks like a data problem but is really a negotiation problem. For how those content headers fit into the wider request, including character encoding and compression, read content types and encoding, which covers the surrounding plumbing in full.