7

I've switched back and forth ~5 times already. This REST endpoint at /api/tags/ will be for internal use (no 3rd party clients), I'm the only one working with it.

I'm deciding between these two representations:

Flat

{  
   "types":[  
      {  
         "id":1,
         "text":"Utility"
      },
      {  
         "id":7,
         "text":"Lease Terms"
      },
   ],
   "tags":[
      {  
         "id":8,
         "text":"Water",
         "type":1
      },
      {  
         "id":9,
         "text":"Electricity",
         "type":1
      },
      {  
         "id":5,
         "text":"Minimum 12 month lease",
         "type":7
      },
      {  
         "id":17,
         "text":"lease negotiable/flexible",
         "type":7
      },
   ]
}
  • It's somewhat modular. Can add another top layer such as "country" without breaking compatibility.

Nested

{  
   "1":{  
      "text":"Utility",
      "tags":{  
         "8":{  
            "text":"Water"
         },
         "9":{  
            "text":"Electricity"
         },
      }
   },
   "2":{  
      "text":"Lease Terms",
      "tags":{  
         "5":{  
            "text":"Minimum 12 month lease"
         },
         "17":{  
            "text":"lease negotiable/flexible"
         },
      }
   },
}
  • It's already in a usable format. Don't need to loop through data before using it.
  • Saves some bandwidth. Even after gzip, this is slightly smaller.

Which one should be used, and why? If this is a matter of personal preference, which representation would experienced developers prefer and why?

  • Is this a matter of personal preference?. I think so. Requirements > needs > preferences – Laiv Jun 10 '17 at 21:19
  • @Laiv In that case, my question should be rephrased "Which representation do experienced developers prefer and why?" – dtgq Jun 10 '17 at 21:34
  • Are these id's stable over time and ok for the client to remember and use later, or, are they just message local? – Erik Eidt Jun 10 '17 at 23:35
  • @ErikEidt They're permanent, database primary keys. – dtgq Jun 11 '17 at 0:34
  • Do you consider Water more as a subclass of Utility or more as an instance of Utility? – Erik Eidt Jun 11 '17 at 0:43
5

Depends on your use case.

When using JSON with a statically typed language, there is a huge bonus if your structure maps into your types. This means that all the names of the keys should be known in advance.

So, if you plan to use Java to consume the service, or if you plan to document it with JSON Schema, number one will be much cleaner (of course both will work).

2

Hard to say without enough context. I have worked with both formats but I tend to structure the data as the option #1. In general, I prefer simplicity over sophistication. While #2 could be synonymous with efficiency, the first is synonymous of readability which I think is often a more relevant feature.

Data structures and the relationship between them are obvious in option #1, whereas the second implies a different way of thinking. For some people, tree structures are not so explicitly self-descriptives. Think of junior developers who barely have seen a composition/aggregation deeper than Person > Address.

Being simplistic, I could read the first approach as:

  • there's a collection of typed tags.

But, how could I describe the second approach in only 6 words? I guess It's possible, but it's not so obvious at the first glance.

Exemple:

"tags":{ "5":{ "text":"Minimum 12 month lease" }, "17":{ "text":"lease negotiable/flexible" }

If I were unfamiliar with JSON and tree structures I could read that structure as:

  • entity tags has two attributes: 5 and 17 but I don't know the type. Whatever the type is, has only one attribute: text

Don't get me wrong, the second option could be a smarter solution, but I would not sacrifice readability by cleverness or sophistication.

We here use the expression "Happy idea". A Happy idea could make sense to me and make none for others, or to be hard to explain.

As I said, I have worked with both approaches. I actually do. In my current project, I have to integrate the backend with a 3rd party web service which responses are very similar to the option #2. As Java developer I am, I agreed with @fdreger. The deserialization of the web service response is anything but readable because there's not direct mapping over getters/setters and classes. I have had to loop over the structure using the API of the mapper: getNode, getSiblings, getNodeName, getChildAsText, isNodeObject, isText, etc.... The web service provides us with a calendar: year, months, days, hours of the day, etc. I could manage it to transform their tree into a collection of timestamps!!! Which do you think is easier to map and to work with?

For a language like Javascript, the mapping is transparent and straightforward. I wonder if It's also for Python. I know that OOP is optional in Python and maybe it makes the language much less typed and flexible, like Javascript.

However, designing a data structure over the language capabilities It's somewhat a way to expose implementation details and condition the integration to languages with these specific capabilities.

0

If you didn't want anything else, you could just use:

{
    "Utility": {
        "8": "Water",
        "9": "Electricity"
     },
     "Lease Terms": {
        "5": "Minimum 12 month lease",
        "17": "lease negotiable/flexible"
     }
}

Unfortunate here that JSON only allows strings as keys.

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

Not the answer you're looking for? Browse other questions tagged or ask your own question.