JSON in REST APIs

JSON (JavaScript Object Notation) is the lingua franca of modern APIs. Nearly every REST service you will encounter accepts and returns JSON, so reading and shaping it fluently is a core skill. In this lesson we cover JSON syntax, how it flows through requests and responses, and the conventions that separate clean API payloads from messy ones.

JSON Syntax in Two Minutes

JSON has exactly six value types: strings, numbers, booleans, null, arrays, and objects. Keys must be double-quoted strings, and there are no comments or trailing commas.

json

{
  "id": 314,
  "title": "Wireless Mouse",
  "price": 24.5,
  "inStock": true,
  "tags": ["electronics", "accessories"],
  "warranty": null,
  "dimensions": { "widthCm": 6.2, "lengthCm": 10.8 }
}

Notably missing: dates, binary data, and undefined. Dates are conventionally sent as ISO 8601 strings like "2026-07-20T14:30:00Z", and binary data is either base64-encoded or, better, served from a separate URL.

JSON in the Request-Response Flow

When a client sends JSON, two things must happen: the body contains serialized JSON text, and the Content-Type header declares application/json so the server knows how to parse it. The server responds in kind, setting its own Content-Type on the way back.

In JavaScript the bridge between objects and JSON text is a pair of built-ins: JSON.stringify turns an object into a string for sending, and JSON.parse turns received text back into an object. Most frameworks do this for you: Express with express.json() middleware, and fetch with response.json().

Designing Clean JSON Payloads

Good API payloads follow a few widely shared conventions:

Consistent key casing. Pick camelCase or snake_case for the whole API. Mixing both forces every client to write mapping code.
Meaningful nesting. Group related fields (an address object inside a user) but avoid nesting more than two or three levels deep.
Predictable envelopes. Many teams wrap list responses in an object, like {"data": [...], "meta": {"total": 132}}, leaving room for pagination info without breaking clients later.
Never return raw arrays at the top level if you may ever need to add metadata; an object envelope is future-proof.
Stable types. A field that is sometimes a number and sometimes a string will break strongly-typed clients in Java, Swift, or TypeScript.

Common JSON Pitfalls

Watch out for these classics. Large integers: JavaScript numbers lose precision beyond 2^53, so 64-bit database IDs are often sent as strings. Floating-point money: send prices in minor units ("amountCents": 2450) or as strings to avoid rounding bugs. Parsing errors: a client sending invalid JSON should receive 400 Bad Request, not a 500 crash, so always handle parse failures. Character encoding: JSON is UTF-8 by default; do not fight it.

A Real-World Example

Imagine a weather API response designed with these rules:

json

{
  "data": {
    "city": "Mumbai",
    "observedAt": "2026-07-20T09:00:00Z",
    "temperatureC": 29.4,
    "conditions": ["humid", "cloudy"]
  },
  "meta": { "source": "station-114", "units": "metric" }
}

A mobile app, a dashboard, and a partner integration can all consume this without special cases, which is exactly the point of consistent JSON design.

Key Takeaways

JSON has six types; dates go as ISO 8601 strings and money is safest in integer minor units.
Always pair JSON bodies with the application/json Content-Type header.
Keep key casing consistent and wrap lists in an envelope object with room for metadata.
Handle parse errors with 400 responses, and keep every field's type stable.

Next up: HTTP Headers and Content Negotiation, where metadata does the heavy lifting.