MEPX
Chapter 6 of 10All chapters
  1. 1What an API is
  2. 2The request
  3. 3The response
  4. 4REST and its alternatives
  5. 5Authentication
  6. 6JSON and data shapes
  7. 7Pagination and filtering
  8. 8Rate limits and retries
  9. 9Versioning and change
  10. 10Calling and debugging APIs

Chapter 6 of 10

JSON and data shapes

The format everything agreed on.

Why JSON won

It is readable, maps onto the data structures of every language, and has almost no features to argue about. The lack of a date type is its one everyday gap.

  • Send dates as ISO 8601 strings in UTC, such as 2026-09-02T13:45:00Z.
  • Numbers lose precision in JavaScript beyond 2 to the 53, so send large ids as strings.

Consistency

Pick one naming style and keep it. Return an empty array rather than null for an empty list, and keep the same envelope for every response so clients can be written once.