I’ve been working with Data APIs for quite a while. Most of my experience is with RESTful & GraphQL APIs. When I first started a made a mistake that I’ve seen others make. Let’s say you have an endpoint (or query if it is a GraphQL API) and the the main information that is needed from the response is a list of people. From time to time, I’d see something like this returned:
[{
"firstName": "John",
"lastName": "Doe",
"age": 30,
"address": {
"streetAddress": "123 Main St",
"city": "Anytown",
"state": "CA",
"postalCode": "12345"
},
"phoneNumbers": [
{
"type": "home",
"number": "555-1234"
},
{
"type": "work",
"number": "555-5678"
}
]
},{
"firstName": "Jane",
"lastName": "Doe",
"age": 30,
"address": {
"streetAddress": "123 Main St",
"city": "Anytown",
"state": "CA",
"postalCode": "12345"
},
"phoneNumbers": [
{
"type": "home",
"number": "555-1234"
},
{
"type": "work",
"number": "555-5678"
}
]
}]
See the problem here? If you don’t I’ll explain.
The root of the JSON response is an array. While this is indeed valid JSON it is not as flexible as it could, or should, be. For example, let’s say there are some client applications that are already consuming this JSON and now you need to add some metadata about the people in the array. Well, there is no way to do that unless you add the meta data to every item in the array or break the JSON. If the response had an object at the root rather than an array, you could add the additional data like this:
{
"metadata": {
"dataSource": "/path/to/where/the/data/came/from",
"employer": "Company Name, Inc.",
"image": "/path/to/image/that/applies/to/the/people.jpg"
},
"people": [
{
"firstName": "John",
"lastName": "Doe",
"age": 30,
"address": {
"streetAddress": "123 Main St",
"city": "Anytown",
"state": "CA",
"postalCode": "12345"
},
"phoneNumbers": [
{
"type": "home",
"number": "555-1234"
},
{
"type": "work",
"number": "555-5678"
}
]
},
{
"firstName": "Jane",
"lastName": "Doe",
"age": 30,
"address": {
"streetAddress": "123 Main St",
"city": "Anytown",
"state": "CA",
"postalCode": "12345"
},
"phoneNumbers": [
{
"type": "home",
"number": "555-1234"
},
{
"type": "work",
"number": "555-5678"
}
]
}
]
}
So, if you’re writing the schema for a new JSON response, do yourself a favor and design it so that there is an object at the root… even if you only need an array of items. You’ll thank yourself later.
