JSON Fundamentals for APIs
JSON supports objects, arrays, strings, numbers, booleans, and null. API contracts should define which fields are required, optional, nullable, writable, and read-only.
Do not blindly serialize database documents. Database schemas and public API representations serve different purposes. An API may rename fields, omit internal fields, calculate values, combine data from multiple sources, or expose stable identifiers.
For example, an internal document may contain password hashes, audit metadata, internal flags, and database-specific identifiers. None of these should automatically become public API fields.
API Representation
{
"id": "usr_42",
"name": "Suriya",
"email": "suriya@example.com",
"createdAt": "2026-10-12T10:00:00Z"
}💡 The representation exposes public resource fields while avoiding internal database implementation details.