Improve JSON layout

[markberger]

I've been playing around with the web api and navigating the JSON is unnecessarily complicated. For example, this is what I get when I request info on one dirnode:

[
 "dirnode",
 {
  "rw_uri": "URI:DIR2:5bbr...",
  "verify_uri": "URI:DIR2-Verifier:or4r...",
  "ro_uri": "URI:DIR2-RO:4z4rlm...",
  "children": {
   "file-1": [
    "filenode",
    {
     "format": "CHK",
     "verify_uri": "URI:CHK-Verifier:6vwhe...",
     "ro_uri": "URI:CHK:ncwvkn...",
     "mutable": false,
     "size": 73,
     "metadata": {
      "tahoe": {
       "linkmotime": 1374966798.767442,
       "linkcrtime": 1374966798.767442
      }
     }
    }
   ],
   "file-2": [
    "filenode",
    {
     "format": "CHK",
     "verify_uri": "URI:CHK-Verifier:vqtq4...",
     "ro_uri": "URI:CHK:3rbo...",
     "mutable": false,
     "size": 396,
     "metadata": {
      "tahoe": {
       "linkmotime": 1374966841.575218,
       "linkcrtime": 1374966841.575218
      }
     }
    }
   ]
  },
  "mutable": true
 }
]

It doesn't make sense to return a list when I'm requesting info on one directory. The "dirnode" element does not need to preface the map and could instead be the info associated with a type key. This isn't a huge inconvenience, but it makes the children unnecessarily complicated as well. Children should be a map that returns another map.

Also I don't think creating another dictionary for metadata adds any clarity or convenience.

These issues aren't a big deal when you're working with the api in Python or another dynamically typed language, but for statically typed languages this format is painful to parse.

[daira]

Replying to markberger:

I've been playing around with the web api and navigating the JSON is unnecessarily complicated. [...]

It doesn't make sense to return a list when I'm requesting info on one directory.

The outermost level of a JSON object must be a list or a dictionary. In this case we chose to use a list in which the first element gives the type.

While you're right that this could have been done a little more simply (by using a dictionary {"type": "dirnode", ...} rather than a list ["dirnode", {...}] for example), I don't think it is worth the hassle of an incompatible change, which would be very disruptive.

Also I don't think creating another dictionary for metadata adds any clarity or convenience.

I disagree: what would you do about metadata keys that clash with standard fields like "format"? You could disallow a fixed set of strings, but then you'd be prevented from adding more standard fields (because they might clash with existing metadata). You could escape or prefix the metadata keys, but I don't really see that this is simpler than using a nested dictionary.

Thanks for the suggestions, but I'm wontfixing this.