Field Conventions: Names, Dates, Money and Identifiers

Four kinds of field recur in almost every endpoint, and each needs one convention for the whole API: field names in one case, dates as ISO 8601 strings with a time-zone offset, money as an integer count of the smallest unit with a currency code, and identifiers as strings. Settling them once means a client that has read one endpoint can read them all.

Names. Choose camelCase or snake_case and use it everywhere; camelCase is the common choice for JSON. Avoid abbreviations such as cur and repeating the resource, as in order_id inside an order.

Dates. 07/10/2026 is 7 October in Spain and 10 July in the United States, and a time without an offset is ambiguous between time zones. ISO 8601, in the profile RFC 3339 defines, writes 2026-10-07T14:30:00+02:00: year first, and the offset from UTC at the end. Z means UTC.

Money. A JSON number such as 19.99 is often parsed as a floating-point value, a binary format in which 0.1 and 0.2 do not add up to exactly 0.3, so totals drift by fractions of a cent. Send an integer in minor units, cents for euros, with an ISO 4217 currency code such as EUR. A decimal string, "19.99", also works. Do not join amount and currency into one string such as "19.99 EUR", which every client must take apart.

Identifiers. Send ids as strings, even when they are numbers in the database. JavaScript loses precision on integers above 2 to the power 53, and a string leaves room to change the format later.

So decide these four once, write them into the contract, and check every new field against them.