How should you shape and name fields in a JSON API response?

Aim for a shape that is predictable, so a client developer can guess the next field without reading the docs.

{
  "data": [
    { "id": "ord_123", "status": "paid", "total_cents": 4599, "created_at": "2026-10-19T08:30:00Z" }
  ],
  "next_cursor": "eyJpZCI6MTIzfQ"
}

Rules that pay off:

• Pick one naming style, snake_case or camelCase, and use it everywhere.
• Use plural nouns for collections and the same object shape in lists and single reads.
• Wrap lists in an object. A bare array leaves no room to add paging or metadata later without a breaking change.
• Send dates in ISO 8601 with a time zone, ids as strings, and money in minor units or decimal strings.
• Use real booleans and enum strings, and decide once whether an unset value is null or absent.
• Never leak database column names or internal ids that you may want to change.

Consistency matters more than any single choice.