Empty collections return empty array
Why it matters
An endpoint that returns 404 when a collection is empty conflates two distinct states: "this endpoint does not exist" and "this collection has no items." Consumers must add special-case 404 handling to every list call, and any generic list component breaks for new users who have no data yet. Returning null instead of [] causes response.data.map is not a function in every consumer that did not add a null guard. iso-25010:2011 compatibility.interoperability requires a consistent response shape regardless of result count — consumers must be able to write one code path for all list responses.
Severity rationale
Low because inconsistent empty collection handling causes consumer-side null reference errors and forces special-case code without enabling security exploits.
Remediation
Always return an empty array with 200 status and consistent pagination metadata when a collection has no items:
// Before -- inconsistent empty handling:
if (results.length === 0) {
return Response.json({ message: 'No items found' }, { status: 404 })
}
// After -- consistent shape regardless of count:
return Response.json({
data: results, // [] when empty, same shape as non-empty
meta: { page: 1, limit: 20, total: 0, totalPages: 0 }
})
This lets consumers write response.data.map(...) once and have it work whether the array has 0 or 1000 items. The rule is simple: 404 means the endpoint does not exist, never that the collection is empty.
DetectionPro
The detection method for this pattern is part of AuditBuffet Pro.
The full method (what to look for, pass and fail conditions, and how results get reported) ships inside the API Design Audit. The pattern definition, severity rationale, and remediation remain openly licensed under CC-BY-4.0.
External references
- iso-25010:2011 · compatibility.interoperability — Interoperability — consistent empty-collection shape prevents consumer branching on null vs array
Taxons
History
- 2026-04-18·v1.0.0·Initial import from api-design·automated