[katello-devel] JSON API v2 conventions discussion

[Tomas Strachota]

On 07/11/2013 08:06 PM, Martin Bacovsky wrote:
> On 07/10/2013 08:41 AM, Joseph Magen wrote:
>> 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?
> Hammer does not have any preferences in this. We use own tool for
> transformation of the data in json responses which is pretty flexible.
> The current conventions work for us well.
>> 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?
> In Katello API v1 conventions are inconsistent. That is why we created
> API v2 where we tried to stick to Foreman API conventions as much as
> possible.
>> 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"
>>    }]
>> }
>> ---
> If we need to reduce requests I would prefere nesting of resources. From
> the restful interface I would somehow expect to get a post if ask for
> post, nothing more. So my preferred response would look like this (or at
> least that is what we do in Katello API when it makes sense):
>   ---
> {
>    "post": {
>      "id": 1,
>      "title": "Rails is omakase",
>      "comments": [{
>         "comment": {
>           "id": 1,
>           "body": "But is it _lightweight_ omakase?"
>         }
>       },
>       {
>         "comment": {
>           "id": 2,
>           "body": "I for one welcome our new omakase overlords"
>         }
>       },
>       {
>         "comment": {
>           "id": 3,
>           "body": "Put me on the fast track to a delicious dinner"
>         }
>       }]
>    },
> }
> ---
>

This nesting works very well with current cli implementation. It's the 
simplest way. On the other hand it brings redundancy.

I like the idea of side loading. It solves the problem with loading 
related resources effectively. So +1 for that. Maybe we can make it 
optional.

Another solution can be to enable scoped search by ids. Then you could 
load all related comments with one search request (per resource type). 
We will probably need to enable this anyway. We have to translate 
name->id when associating resources in the cli.

T.


> Regards,
> Martin
>>
>> Regards,
>>
>> Joseph
>>
>> _______________________________________________
>> katello-devel mailing list
>> katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel