json JSON formatting/usability

[leonfagan71]

Hello,

I'm updating a project that I made a few years ago, and wanted to update some of the api responses and would really like your feedback on what a better response would be.

 

So this small section displays races, I've formatted the response to make it easier to read.

 

This is the old JSON response from the api:

{
  "races": [
    {
      "race_title": "test",
      "race_id": "1551",
      "race_desc": "I like big butts and I can't deny",
      "race_short_desc": "I like big butts and",
      "race_active": "true",
      "race_map": null,
      "race_image": null,
      "race_cover": "",
    }
  ],
  "count": 1
}

 

 

And this is something that I just typed up:

{
    "races":[
      {
        "race_title":"",
        "race_id":"",
        "race_active":true,
        "extra":{
            "race_desc":"",
            "race_map":{
                "enabled": false,
                "src":""
            },
            "race_image":{
                "enabled": true,
                "src":""
            }
            "race_color":{
                "enabled":false,
                "color":"rgba(255,255,255)"
            }
        }
      }  
    ],
    "count":1
}

I'm looking for a good way I could format the data to seem better.

 

I was going to ask my friends *they exist I swear* however it's 3am and well, they're asleep and I'd rather have a more community response.

 

 

Regards,
Leon.

[icepuma]

The upper "domain model" is much simpler in terms of marshalling / unmarshalling. If the "extra" part given in the second example isn't necessary for the first call, then you could do some deeplinking. But if everything belongs together, I personally would stick to the first example.

 

Edit:

Since facebook got a better licensing for graphql you could look for that. Then you could decide on the client side, what info you need.

Edited October 16, 2017 by icepuma
Add a hint to graphql

[leonfagan71]

7 minutes ago, icepuma said:

The upper "domain model" is much simpler in terms of marshalling / unmarshalling. If the "extra" part given in the second example isn't necessary for the first call, then you could do some deeplinking. But if everything belongs together, I personally would stick to the first example.

 

Edit:

Since facebook got a better licensing for graphql you could look for that. Then you could decide on the client side, what info you need.

Okay, thanks.

So, if I were to remove the extra tag and move the contents into the race array entry like:
 

{
    "races":[
      {
        "race_title":"",
        "race_id":"",
        "race_active":true,
        "race_desc":"",
        "race_map":{
            "enabled": false,
            "src":""
        },
        "race_image":{
            "enabled": true,
            "src":""
        }
        "race_color":{
            "enabled":false,
            "color":"rgba(255,255,255)"
        }
      }  
    ],
    "count":1
}

Then it would be better??

In terms of graphql, as this is the 5th update (last four were complete rewrites) in 4 years, I'd rather not completely remove it all, plus there's lots of complicated stuff in other parts of the api that I would like to keep.

 

Is the key naming okay? race_title, race_desc, race_id. I feel like because this is the /races endpoint that it should just be title, description and id without the race_ prefix.

[icepuma]

You can entirely get rid of the "race_" in every key:

 

{
    "races": [
      {
        "title": "",
        "id": "",
        "active": true,
        "description": "",
        "map": {
            "enabled": false,
            "source": ""
        },
        "image": {
            "enabled": true,
            "source": ""
        }
        "color": {
            "enabled": false,
            "color": "rgba(255,255,255)"
        }
      }  
    ],
    "count":1
}

And better be more descriptive, like "description" instead of "desc"

[leonfagan71]

2 minutes ago, icepuma said:

You can entirely get rid of the "race_" in every key:

 

{
    "races": [
      {
        "title": "",
        "id": "",
        "active": true,
        "description": "",
        "map": {
            "enabled": false,
            "source": ""
        },
        "image": {
            "enabled": true,
            "source": ""
        }
        "color": {
            "enabled": false,
            "color": "rgba(255,255,255)"
        }
      }  
    ],
    "count":1
}

And better be more descriptive, like "description" instead of "desc"

Thanks, it helps a lot, I'm just really bad at naming things.
I called something doEntryStuff.php at one point :D 

[icepuma]

Treat your code like you would treat an essay. Just be as descriptive as you can. Don't name a variable "a", don't be short! Write meaningful method names.