[katello-devel] JSON API v2 conventions discussion

[Walden Raines]

I personally prefer traversing the ids in the child nodes.

What does putting the _ids in an array in the root node give you?  Wouldn't you still need to link each individual post/comment to the _ids array?

As far as "sideloading" goes, I guess it all comes down to a balance of TMI and reducing HTTP requests.  I tend to be more on the side of reducing requests since that is likely where most of the application's latency is.

I would change your example to look like this:

GET /posts/

{
     "total": 10,
     "limit": 2,
     "offset" 3,
     "results": [
        {
            "id": 1,
            "title": "Rails is omakase",
            "comments": [
                {
                    "id": 1,
                    "body": "But is it _lightweight_ omakase?"
                },
                {
                    "id": 2,
                    "body": "I for one welcome our new omakase overlords"
                },
                {
                    "id": 3,
                    "body": "Put me on the fast track to a delicious dinner"
                }
            ]
        },
        {
            "id": 2,
            "title": "Rails is omakase",
            "comments": [
                {
                    "id": 5,
                    "body": "But is it _lightweight_ omakase?"
                },
                {
                    "id": 6,
                    "body": "I for one welcome our new omakase overlords"
                },
                {
                    "id": 10,
                    "body": "Put me on the fast track to a delicious dinner"
                }
            ]
        }
    ]
}

And the individual GET to /post/:id would return one of those hashes in the results array.  To me, a comment is a sub-resource of a post (I'm making the assumption that a comment cannot exist without a post).

For what it's worth, I've used Ember.js at a past company and I am not a fan.  It seemed convoluted, poorly documented, and slow (though to be fair, it wasn't yet 1.0 when we were using it).

AngularJS, on the other hand, is straightforward, well documented, and fast.

Cheers,
Walden


----- Original Message -----
From: "Joseph Magen" <jmagen at redhat.com>
To: "foreman-dev" <foreman-dev at googlegroups.com>, katello-devel at redhat.com
Sent: Wednesday, July 10, 2013 2:41:12 AM
Subject: [katello-devel] JSON API v2 conventions discussion

I've been reading how different API clients prefer different JSON responses and that there is no standard "convention over configuration".  For example, Ember.js prefers the _ids as an array in the root node, whereas other JS clients prefers to transverse the id's in the child nodes. (see ex. below)

My questions:
1) Is there a particular API JSON convention that the Foreman Hammer CLI prefers?
2) Is Katello consuming the Foreman API or plan to in the future?
3) Is Foreman consuming the Katello API or plan to in the future?  
4) Are the Katello API and Foreman API v1 conventions similar or different?
5) What other JSON clients / frameworks do we know about that are big consumers of Foreman API

Here is an example of side-loaded relationships from the Ember.js documetation.

http://emberjs.com/guides/models/the-rest-adapter/#toc_sideloaded-relationships

---
To reduce the number of HTTP requests necessary, you can sideload additional records in your JSON response. Sideloaded records live outside the JSON root, and are represented as an array of hashes:

{
  "post": {
    "id": 1,
    "title": "Rails is omakase",
    "comment_ids": [1, 2, 3]
  },

  "comments": [{
    "id": 1,
    "body": "But is it _lightweight_ omakase?"
  },
  {
    "id": 2,
    "body": "I for one welcome our new omakase overlords"
  },
  {
    "id": 3,
    "body": "Put me on the fast track to a delicious dinner"
  }]
}
---

Regards,

Joseph

_______________________________________________
katello-devel mailing list
katello-devel at redhat.com
https://www.redhat.com/mailman/listinfo/katello-devel