Is it a good practice to make API response list of values as dictionary?

Question

I have an API endpoint that returns some statistics. Currently the response looks like:

Option 1:

{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ],
    ... other keys
}

But this looks a bit complex and I what to make it like:

Option 2:

{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
    ... other keys
}

I understand that Option 1 is easier to be extended, but less comfortable for users. What other issues I can face using one of these options? Or should I make a hybrid solution like:

Option 3:

{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            },
    ... other keys
}

The keys "some-stats-key1" and "some-stats-key2" are just internal values and it's expected API user will map them into readable names using documentation. All the keys are unique.

The order of "stats" isn't important.

The typical use case is just to get all the stats, match keys with readable names and show as a table on a web-page. But currently I can't say if no one will need only a part of the stats later.

Is there a best practice for this issue?

Answer 1

I'd go for option 2. If the API consumer will convert some-stats-key1 into something readable, that probably means he/she has a list of values he/she is interested in (say, some-stats-key1 and some-stats-key3), and will iterate over that list. By choosing a JSON object, it will be deserialized as a dictionary/map which provides a convenient lookup for the consumer of the API.

This will be more cumbersome with option 1, where the consumer needs to iterate over the JSON array, or pre-create their own dictionary with interesting keys.

Option 3 is a little too verbose for me, the duplication of the key names just doesn't appeal to me.

If extensibility is a concern, you can always publish a v2 of your API returning something like

"stats": {
    "some-stats-key1": { "value": 10, "error-margin": 0.1 },
    "some-stats-key2": { "value": 20, "error-margin": 0.2 }
}

and keep the v1 for backwards compatibility. Maintaining backwards compatibility within a single version of the API can be a real PITA if you don't have complete control over how the API is consumed. I've seen a consumption of an API of mine 'break' when I just added an extra (optional) key-value pair (i.e. not changing the structure).

Answer 2

The two options have the classic List vs. Map advantages.

1) The List allows duplicate entries and maintains order. If these features are important, use the List, even though it is clunkier.

2) The Map does not allow duplicates. Maintaining order is possible with a little extra work. The big advantage is more simplicity in the data format, and searching for a particular element is trivial.

My default choice is always the simpler Map, but YMMV.

Answer 3

When I get data from an API, I always check that everything is as I expect it. So my effort to process your data consists of the verification, and the actual processing.

In case 1 I have to check: a. There is an array. b. All items in the array are dictionaries. c. Every dictionary has a key "name". d. All values for the "name" key are unique.

In case 3 I have to check: a. There is a dictionary. b. All values in the dictionary are dictionaries. c. Each dictionary has a key "name" with a value that matches the key in the outer dictionary. Slightly better.

In case 2 I have to check: a. There is a dictionary.

(Of course I have to check the values as well). So your case 2 requires the least amount of checking on my side. I actually get a data structure that is immediately usable.

The only problem with 2 is that it is not extendible. So instead of sending the value as a number, you might send { value: 10 } which can then be extended in a backward compatible way.

Redundancy is bad. The only thing that redundancy achieves is to make me write more code, and forcing me to think about what I should do if the redundant bits don't agree. Version 2 has no redundancy.

Answer 4

Since you asked of good practices for API design:

• I never return an api response containing an object at the top level. All service calls return a set (as an array), and that set contains elements (as object instances.) The number of objects returned in the array is irrelevant to the server. If the client needs to make a determination from the number of items returned in the response, that burden is the client's to enforce. If a single item is expected, it gets returned as a unit set
• When I'm designing an api, I don't presume to know what specific technology my api clients will be using to consume said api, even when I know what specific technology they are most likely to use. My responsibility is to communicate my domain representations consistently to all consumers, not conveniently to a particular consumer.
• If a structural option exists to allow the response to be composed, this structure takes priority over options which do not
• I strive to avoid creating representations that have unpredictable structures.
• If the structure of a representation can be predicted, then all instances inside the response set should be of the same representation and the response set should be internally consistent.

---

So, given the structures you've proposed, the structure I would implement would look something similar to this

[
   { /* returns only the 'common' metrics */
      "stats": [
                  {"key":"some-metric1","value":10},
                  {"key":"some-metric2","value":20}
               ]
   },
   { /* returns an optional metric in addition to the "common" metrics */
      "stats": [
                  {"key":"some-metric1","value":15},
                  {"key":"some-metric2","value":5},
                  {"key":"some-optional-metric", "value":42}
               ]
   },
   { /*returns the 'common' metrics as well as 2 candidates for "foo-bar" */
      "stats": [
                  {"key":"some-metric1", "value": 5},
                  {"key":"some-metric2", "value": 10},
                  {"key":"foo-bar-candidate", "value": 7},
                  {"key":"foo-bar-candidate", "value": 11}
               ]
   }
]