All Dressed Programming

Returning Lists Of Items In JSON APIs

It happens often that we need to implement an endpoint that returns a list of items with a “canonical” id. A typical example is a /users endpoint that returns a list of users. In this post, I will advocate for returning a list of objects each of which contains an id key and not a single object where ids are associated with their canonical values. // Good [ {id: 1, name: 'Emelia', age: 12}, {id: 2, name: 'Cassidy', age: 96} ] // Bad { 1: {name: 'Emelia', age: 12}, 2: {name: 'Cassidy', age: 96} } Communicate Intent The first reason to return a list of items is that, semantically, it is what the endpoint returns.