Tweeted twitter.com/StackSoftEng/status/882546271239761922
3 added 250 characters in body
source | link

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.

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:

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.

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.

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:

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:

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.

2 added 65 characters in body
source | link
{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ],
    ... other keys
}
{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
    ... other keys
}
{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            },
    ... other keys
}
{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ]
}
{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
}
{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            }
}
{
    "stats": [
                {
                    "name": "some-stats-key1",
                    "value": 10
                },
                {
                    "name": "some-stats-key2",
                    "value": 20
                }
            ],
    ... other keys
}
{
    "stats": {
                "some-stats-key1": 10,
                "some-stats-key2": 20
            }
    ... other keys
}
{
    "stats": {
                "some-stats-key1": {
                                        "name": "some-stats-key1",
                                        "value": 10
                                    },
                "some-stats-key2": {
                                        "name": "some-stats-key2",
                                        "value": 20
                                    },
            },
    ... other keys
}
1
source | link

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

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
                }
            ]
}

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

Option 2:

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

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.

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:

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

Is there a best practice for this issue?