REST API Data Formats

Two systems can both speak JSON and still misunderstand each other. One writes a date as 03/04/2026, and the other reads it as April 3 while the sender meant March 4. Clear data format rules remove this guesswork and prevent costly bugs.

The Shared Language Picture

Travelers write addresses in different orders depending on the country. A parcel service solves this problem by publishing one official address format. APIs need the same kind of official format for dates, money, and other values.

Dates and Times

Use the ISO 8601 standard. It writes the year first, then the month, day, and time, so every reader gets the same meaning. Store and send times in UTC, and mark UTC with the letter Z.

Date only:       2026-11-02
Date and time:   2026-11-02T14:30:00Z
With offset:     2026-11-02T20:00:00+05:30

Let the client convert UTC into the local time zone for display. Servers that mix local times create bugs around daylight saving changes.

Money

Floating point numbers cannot store decimal money exactly. The value 0.1 plus 0.2 equals 0.30000000000000004 in many languages. Use one of two safe patterns.

Pattern 1: integer in the smallest unit
{ "amount": 4999, "currency": "USD" }       means 49.99 dollars

Pattern 2: decimal string
{ "amount": "49.99", "currency": "USD" }

Always send the currency code from the ISO 4217 list, such as USD, EUR, or INR.

Identifiers

Send ids as strings. Some systems lose precision on very large integers, and strings avoid that loss. Strings also let you switch from numbers to UUIDs later without breaking clients.

{ "id": "9007199254740993" }
{ "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }

Null, Missing, and Empty

Form	Meaning
"phone": null	The field exists and holds no value
Field absent	The server did not send it, or the client did not change it
"phone": ""	An empty text value
"tags": []	An empty list

Document which form your API uses. In PATCH requests, a missing field means "leave alone", and null means "clear this value".

Booleans and Enumerations

Use true and false for booleans, never "yes", "Y", or 1. Use short, lowercase text for fixed choices.

{ "status": "shipped" }

Allowed values: pending, paid, shipped, delivered, cancelled

List allowed values in the documentation, and reject unknown values with a clear validation error.

Numbers, Units, and Measurements

Name the unit in the field or in a companion field. A field called weight tells nobody whether it counts grams or pounds. Use weightGrams, or send an object with value and unit.

{ "weight": { "value": 450, "unit": "g" } }

Language and Region

Use IETF language tags such as en, hi, or pt-BR. Use ISO 3166 country codes such as IN, US, and DE. Send raw values and let clients format them for display, including thousand separators and decimal marks.

Envelope or No Envelope

Some APIs wrap data in an outer object, such as { "data": {...}, "meta": {...} }. Others return the resource directly. Both work. Pick one pattern, and keep it across every endpoint.

{
  "data": [ { "id": "1", "title": "Atlas" } ],
  "meta": { "total": 120, "page": 1 }
}

Common Mistakes

Local Times Without Offset

A value like 2026-11-02 14:30 leaves readers guessing the zone. Always include Z or an offset.

Money as Floats

Rounding errors accumulate across thousands of orders. Use integers or strings.

Inconsistent Formats Across Endpoints

A date that appears as a timestamp in one response and as text in another forces clients to write special cases. Apply one rule everywhere.