Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 39 ยท Designing Resources and Endpoints

Designing JSON Payloads

Design consistent JSON for your REST API: naming style, dates, money, IDs, null versus missing fields, enums, envelopes and how to hide internal fields.

JSON is the language your API speaks. Once clients parse your fields, renaming or retyping them breaks real programs, so the shape of your payloads deserves as much thought as your URLs. The goal is a representation that is predictable, hard to misuse and does not leak your database layout.

This lesson collects the decisions you make for almost every API: names, types, dates, money, identifiers, null, enums and envelopes.

One naming style, everywhere

Pick one key style and use it in every response and request. The two common choices:

  • camelCase (createdAt, firstName): natural for JavaScript clients and the style of most modern JSON APIs.
  • snake_case (created_at, first_name): natural for Python and Ruby backends, and common in older public APIs.

Neither is wrong. Mixing them is. Your database columns may use another style than your API; convert at the boundary (see the serializer below) so internal naming never leaks.

Name collections with plural words (books, tags) and single values with singular words (author, title). Avoid abbreviations and avoid names that mean different things in different places (type in one resource and kind in another for the same idea).

Choose types carefully

JSON has only strings, numbers, booleans, null, arrays and objects. Everything else is a convention you must define.

Value Recommended representation Why
Timestamp ISO 8601 / RFC 3339 string in UTC: "2026-03-01T14:30:00Z" Unambiguous, sortable, parsed everywhere
Date only "2026-03-01" No fake time or time zone
Money Integer in the smallest unit ("amount": 1999, "currency": "USD") or a decimal string Floats cannot represent 0.1 exactly
Identifier String ("id": "42") Avoids 64-bit integer loss in JavaScript, and lets you change the scheme later
Boolean true / false Not "yes", 1 or "true"
Enum Lowercase string ("status": "shipped") Readable, extensible
Duration Integer with a named unit ("timeoutSeconds": 30) or ISO 8601 ("PT30S") Unit is obvious

Avoid Unix timestamps in seconds as the only date format (readable by machines only), locale-formatted dates ("03/04/2026" is March 4 or April 3?), and money as floating point.

Null, absent and empty

Three different states often get mixed up:

  • A field absent from a response might mean "not applicable", "not requested" (when the client asked for specific fields) or "unknown".
  • A field set to null means "this resource has the field, and it currently has no value".
  • An empty string or empty array means "there is a value, and it is empty".

Choose a rule and document it. A practical approach: always include fields that belong to the resource (returning null when empty) so clients can rely on a stable shape, and leave out only fields the client did not ask for. For updates, the distinction matters even more: in a PATCH merge patch, an absent key means "leave it alone" while null means "clear it".

Envelopes

An envelope wraps data in an object: {"data": {...}} or {"data": [...], "meta": {...}}.

  • A bare resource ({"id": "42", "title": "Dune"}) is simplest for single items.
  • For collections, return an object, never a top-level array, because an object can grow meta and links fields later (pagination, totals) without breaking clients. A top-level array can never be extended compatibly.
JSON
{
  "items": [
    { "id": "42", "title": "Dune", "priceCents": 1299, "currency": "USD" }
  ],
  "meta": { "count": 1 }
}

Errors use their own consistent shape, covered in Error Responses.

Do not expose your database

Your table has password_hash, deleted_at and internal_notes. The API representation should be built deliberately from an allow-list of fields, not by dumping a database row. A function that turns an internal record into a public one (a serializer or transformer) is the safest place to rename keys, format dates, convert money and drop secrets.

Node.js A serializer: from database row to API representation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

If the serializer is the only place that builds responses, adding a sensitive column to the table can never leak it by accident.

Numbers and precision traps

Two numeric pitfalls cause real production bugs. JavaScript numbers are IEEE 754 doubles, so decimals are inexact and integers above 2^53 lose precision.

Node.js Why money and big IDs need care

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The parsed id ends in ...992 instead of ...993: a silent corruption that sends the client to the wrong record. Sending ids as strings avoids it entirely.

Level 3 APIs add links to the representation so clients can follow them instead of building URLs:

JSON
{
  "id": "42",
  "title": "Dune",
  "links": {
    "self": "/books/42",
    "author": "/authors/7",
    "reviews": "/books/42/reviews"
  }
}

Links make an API self-describing and let you move URLs later. Many APIs add at least self and the pagination links next / prev.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should a collection endpoint return an object such as {"items": [...]} instead of a bare array?

    A top-level array cannot be extended compatibly. An envelope leaves room for pagination metadata.
  2. 2. What is the safest way to represent 19.99 US dollars?

    Integer minor units avoid floating point errors and are unambiguous with a currency code.
  3. 3. Which date format is recommended for JSON APIs?

    ISO 8601 / RFC 3339 strings are unambiguous, sortable and parsed by every platform.
  4. 4. In JSON, what does a field set to null usually mean compared with an absent field?

    Decide and document the difference, especially for updates where absent means "keep" and null means "clear".
  5. 5. Why are numeric IDs often sent as strings?

    Numbers above 2^53 lose precision in JavaScript, and opaque string IDs let you change the scheme later.

Summary

  • Pick one key style (camelCase or snake_case) and use it everywhere.
  • Use ISO 8601 UTC strings for timestamps, integer minor units (plus currency) for money and strings for IDs.
  • Decide what null, absent and empty mean, and document it.
  • Return objects, not bare arrays, for collections so you can add meta and links.
  • Build responses with a serializer that allow-lists fields and never exposes database internals.

Next: Filtering, Sorting and Query Parameters