[rest-practices] JSON style guidelines?

[Mark McLoughlin]

Hi James,

On Fri, 2010-05-21 at 10:46 -0400, James Bowes wrote: 
> Hi all:
> 
> For Candlepin, our primary media type is JSON. We've been using
> RESTEasy with Jettison, which does:
> JAXB annotated object -> XML -> JSON
> As such, we're really representing the XML mappings of our objects in
> JSON, rather than the objects themselves. Jettison is doing this with
> the BadgerFish mapping convention, so we get JSON like:
> {
>   "consumer" : {
>     "name" : "my consumer",
>     "facts" : {
>       "entry" : [
>         { "key" : "memory", "value" : 12345 },
>         { "key" : "memory.free", "value" : 60 }
>       ]
>     }
>   }
> }
> 
> My feeling is that if you're using JSON, you want it to be as compact as
> possible. To that end, I've been working on using Jackson instead, which
> cuts out the XML middleman, giving us JSON like:
> {
>   "name" : "my consumer",
>   "facts" : {
>     "memory" : 12345,
>     "memory.free" : 60
>   }
> }

In rhevm-api, we initially went with Jettison and BadgerFish, but
without giving it much thought.

You make a good point about compactness, I think we'll trying moving to
Jackson too. 

> The mapping of the "facts" hash is much nicer, but you do lose that
> beginning "consumer" type hint. I was thinking we could add a
> "type_hint" field inside the returned object instead, or just rely on
> the client to know what type to expect based on the url they hit.

One place this would hurt us in rhevm-api is that our error handling
will return a <fault> description, so e.g.

  PUT /resources/12345 HTTP/1.1
  Content-Type: application/xml

  <resource id="5321"/>

  HTTP/1.1 409 Conflict
  Content-Type: application/xml

  <fault>
    <reason>Broken immutability constraint</reason>
    <detail>Attempt to set immutable field: id</detail>
  </fault>

i.e. the client is expecting a <resource> returned, but we actually
return a <fault>. The only way the client could predict that is to look
at the status code or the root element of the document. With the JSON
mapping you describe, you lose the equivalent of the root element

Bill makes a valid point that if we instead used explicit media types
for the different formats, things would be a lot clearer for the client 

> What is the opinion of the list? Is anyone aware of any gotchas with the
> various JSON styles for autogenerating class representations?

Btw, it'd be cool if you could roughly document the mapping here:

  http://fedoraproject.org/wiki/Cloud_APIs_REST_Style_Guide#JSON

Would also be good to know what mapping JSON deltacloud is using?

Cheers,
Mark.