API Design - Returning Data from several years - json

Question

I'm currently designing a new API.
One of the methods should return some data about a basic object and there are some numeric values that are changing over the years.
Here is a basic example of the object :
{
"id" : 1,
"city_name" : "New York",
"inhabitants" : 10000,
"houses" : 100
}
The goal of the API is to be able to retrieve this data over the years and to pass a table of years as input parameter.
(Also should you pass a table if you only need one year of data ?)
So here are the input parameters :
{
"id" : 1,
"years" : ["2020", "2021"]
}
What is the best data structure to return the data over the years ? Is it Restful ?
The API should be designed to be used by several external consumers.
Here are my experiments so far :
1 - Returning a table like :
[
{
"2020" : {
"id" : 1,
"city_name" : "New York",
"inhabitants" : 9000,
"houses" : 90
}
},
{
"2021" : {
"id" : 1,
"city_name" : "New York",
"inhabitants" : 10000,
"houses" : 100
}
}
]
The problem is that you would need to parse the table and each entry to use the values for a specific year.
2 - Returning the values nested :
{
"id" : 1,
"city_name" : "New York",
"inhabitants" : {
"2021" : 10000,
"2020" : 9000
}
"houses" : {
"2021" : 100,
"2020" : 90
}
}

Answer 1

I think it really depends on what you want to do with the view model the REST API returns. You can support multiple view models if you create multiple REST resources for it:
/api/x/1
{
"id" : 1,
"city_name" : "New York",
"inhabitants" : 10000,
"houses" : 100
}
/api/x/1/history
[
{
"year": "2020",
"id" : 1,
"city_name" : "New York",
"inhabitants" : 9000,
"houses" : 90
},
{
"year": "2021",
"id" : 1,
"city_name" : "New York",
"inhabitants" : 10000,
"houses" : 100
}
]
/api/x/1/events
[
{
"type": "change",
"year": "2020",
"inhabitants" : 9000,
"houses" : 90
},
{
"type": "change",
"year": "2021",
"inhabitants" : 10000,
"houses" : 100
}
]
/api/x/1/plot
[
{
"year": "2020",
"inhabitants" : 9000,
"houses" : 90
},
{
"year": "2021",
"inhabitants" : 10000,
"houses" : 100
}
]
So instead of having a single general view model I would make separate view models fulfilling very specific needs. If you don't understand what your consumers need, then ask them. In my experience guessing takes several months and the consumers can tell you the same info in 5 mins.