Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
belongs to operating system
"operatingsystem_id" => 7,
"operatingsystem_name" => "Rhel 6.3",
has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet's net address,
template's kind, smart proxy's url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it's a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource's base.json.rabl view.
What do you think?
Regards
Tomas
Tomas,
Both are fine. It's a matter of preference. I don't know of a standard "best practice" to display belongs_to associations in the root node or in a child node.
I think easier in a collection of objects (ex. hosts) to show the _name fields in the root node like we're doing it, but I understand your point.
{
"name": "fdev2.examplecom",
"id": 394,
"environment_id": 1,
"environment_name": "production",
I'm open to either way. Maybe the best option is to have an option to show belongs_to in the root or as child nodes.
Joseph
···
----- Original Message -----
> From: "Tomas Strachota"
> To: foreman-dev@googlegroups.com
> Sent: Tuesday, April 22, 2014 6:31:47 PM
> Subject: [foreman-dev] api v2 - displaying associations in json responses
>
> Hello,
> I came across an api v2 feature that started to seem a bit inconsistent
> to me.
>
> In the api index and show responses we handle has_many and belongs_to
> relationships differently. Using rabl terminology, has_many associations
> are modeled as child nodes with very limited fields (defined in
> base.json.rabl) while belongs_to associations are modeled as first-level
> attributes.
>
> Example to make it clear:
> {
> # belongs to operating system
> "operatingsystem_id" => 7,
> "operatingsystem_name" => "Rhel 6.3",
>
> # has many organizations
> "organizations" => [
> [0] {
> "id" => 1,
> "name" => "ACME_Corporation",
> "title" => "ACME_Corporation"
> }
> ]
> }
>
> I know the decision to model it this way has been made based on some
> discussion and it also seemed quite fine to me until I started working
> with it. After playing with the api when implementing associated
> resources for hammer, I find child nodes and the possibility to add more
> fields than name and id extremely handy.
>
> In many cases it is useful to display additional information with the
> association to help user get oriented (e.g. subnet's net address,
> template's kind, smart proxy's url). It is of course possible to
> retrieve the desired information by performing additional gets to
> appropriate resources but it's a bit annoying. Another benefit is
> consistency and ease of use when you can treat both types of
> associations equally.
>
> My proposal is to turn all associations into child nodes displaying
> resource's base.json.rabl view.
> What do you think?
>
> Regards
> Tomas
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
I agree with Tomas. Experience showed that the previous decision on
associations format was not very practical from client perspective.
Using child nodes would make our API more consistent and flexible (using
base rabls ads a lot more potential and DRYness).
It seems that to make the childnodes optional would adds extra
complexity with little benefits so it seems not worth the effort. During
earlier discussions configurability of the API format was advocated with
need to satisfy format requirements of some API consumers (Angular,
others?) - is this still valid? @Joseph, are there any other reasons to
make it configurable?
Martin
···
On 04/22/2014 05:31 PM, Tomas Strachota wrote:
> Hello,
> I came across an api v2 feature that started to seem a bit
> inconsistent to me.
>
> In the api index and show responses we handle has_many and belongs_to
> relationships differently. Using rabl terminology, has_many
> associations are modeled as child nodes with very limited fields
> (defined in base.json.rabl) while belongs_to associations are modeled
> as first-level attributes.
>
> Example to make it clear:
> {
> # belongs to operating system
> "operatingsystem_id" => 7,
> "operatingsystem_name" => "Rhel 6.3",
>
> # has many organizations
> "organizations" => [
> [0] {
> "id" => 1,
> "name" => "ACME_Corporation",
> "title" => "ACME_Corporation"
> }
> ]
> }
>
> I know the decision to model it this way has been made based on some
> discussion and it also seemed quite fine to me until I started working
> with it. After playing with the api when implementing associated
> resources for hammer, I find child nodes and the possibility to add
> more fields than name and id extremely handy.
>
> In many cases it is useful to display additional information with the
> association to help user get oriented (e.g. subnet's net address,
> template's kind, smart proxy's url). It is of course possible to
> retrieve the desired information by performing additional gets to
> appropriate resources but it's a bit annoying. Another benefit is
> consistency and ease of use when you can treat both types of
> associations equally.
>
> My proposal is to turn all associations into child nodes displaying
> resource's base.json.rabl view.
> What do you think?
>
> Regards
> Tomas
>
+10 rendering belongs_to with base.json.rabl
It's simpler, more consistent, and reuses template (less code to maintain).
···
On 22.04.14 17:31, Tomas Strachota wrote:
> Hello,
> I came across an api v2 feature that started to seem a bit inconsistent
> to me.
>
> In the api index and show responses we handle has_many and belongs_to
> relationships differently. Using rabl terminology, has_many associations
> are modeled as child nodes with very limited fields (defined in
> base.json.rabl) while belongs_to associations are modeled as first-level
> attributes.
>
> Example to make it clear:
> {
> # belongs to operating system
> "operatingsystem_id" => 7,
> "operatingsystem_name" => "Rhel 6.3",
>
> # has many organizations
> "organizations" => [
> [0] {
> "id" => 1,
> "name" => "ACME_Corporation",
> "title" => "ACME_Corporation"
> }
> ]
> }
>
> I know the decision to model it this way has been made based on some
> discussion and it also seemed quite fine to me until I started working
> with it. After playing with the api when implementing associated
> resources for hammer, I find child nodes and the possibility to add more
> fields than name and id extremely handy.
>
> In many cases it is useful to display additional information with the
> association to help user get oriented (e.g. subnet's net address,
> template's kind, smart proxy's url). It is of course possible to
> retrieve the desired information by performing additional gets to
> appropriate resources but it's a bit annoying. Another benefit is
> consistency and ease of use when you can treat both types of
> associations equally.
>
> My proposal is to turn all associations into child nodes displaying
> resource's base.json.rabl view.
> What do you think?
>
> Regards
> Tomas
>
Hi Tomas,
Just checking back if there was a resolution on this issue.
Joseph
···
----- Original Message -----
> From: "Tomas Strachota"
> To: foreman-dev@googlegroups.com
> Sent: Tuesday, April 22, 2014 6:31:47 PM
> Subject: [foreman-dev] api v2 - displaying associations in json responses
>
> Hello,
> I came across an api v2 feature that started to seem a bit inconsistent
> to me.
>
> In the api index and show responses we handle has_many and belongs_to
> relationships differently. Using rabl terminology, has_many associations
> are modeled as child nodes with very limited fields (defined in
> base.json.rabl) while belongs_to associations are modeled as first-level
> attributes.
>
> Example to make it clear:
> {
> # belongs to operating system
> "operatingsystem_id" => 7,
> "operatingsystem_name" => "Rhel 6.3",
>
> # has many organizations
> "organizations" => [
> [0] {
> "id" => 1,
> "name" => "ACME_Corporation",
> "title" => "ACME_Corporation"
> }
> ]
> }
>
> I know the decision to model it this way has been made based on some
> discussion and it also seemed quite fine to me until I started working
> with it. After playing with the api when implementing associated
> resources for hammer, I find child nodes and the possibility to add more
> fields than name and id extremely handy.
>
> In many cases it is useful to display additional information with the
> association to help user get oriented (e.g. subnet's net address,
> template's kind, smart proxy's url). It is of course possible to
> retrieve the desired information by performing additional gets to
> appropriate resources but it's a bit annoying. Another benefit is
> consistency and ease of use when you can treat both types of
> associations equally.
>
> My proposal is to turn all associations into child nodes displaying
> resource's base.json.rabl view.
> What do you think?
>
> Regards
> Tomas
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
> Tomas,
>
> Both are fine. It's a matter of preference. I don't know of a standard "best practice" to display belongs_to associations in the root node or in a child node.
>
> I think easier in a collection of objects (ex. hosts) to show the _name fields in the root node like we're doing it, but I understand your point.
>
> {
> "name": "fdev2.examplecom",
> "id": 394,
> "environment_id": 1,
> "environment_name": "production",
>
> I'm open to either way. Maybe the best option is to have an option to show belongs_to in the root or as child nodes.
>
> Joseph
The difference between the approaches as I see it is in the efforts
needed for providing additional information.
We currently send only names and ids. I think it sometimes make sense to
add more fields. If we wanted to display let's say addresses for
associated subnets (we do that for has_many), we'd end up with:
subent_id: …
subent_name: …
subnet_network_address: …
I agree the formatting (prefixing vs. nesting) is matter of preference.
What I see as more important is that nesting and re-using base.json.rabl
templates of referenced resources gives us more flexibility. You add
field to the base template and it appears everywhere. At the moment we
have all *_name and *_id for belongs_to associations "hardcoded" and
distributed across all templates.
I' totally fine with making it optional (per request). I'm not sure how
difficult it would be to implement it though.
Regards
Tomas
···
On 04/23/2014 05:21 PM, Joseph Magen wrote:
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
does this mean that we always include belongs_to attributes in the
default show action?
e.g. host would be something like:
{
name: …
ip: …
operatingsystem: {
id:
name:
major:
…
},
compute_resource : {
}
architecture: { … }
}
or is it an option to "expand" upon request?
Ohad
···
On Mon, Apr 28, 2014 at 11:14 AM, Petr Chalupa wrote:
> +10 rendering belongs_to with base.json.rabl
>
> It's simpler, more consistent, and reuses template (less code to maintain).
>
>
> On 22.04.14 17:31, Tomas Strachota wrote:
>>
>> Hello,
>> I came across an api v2 feature that started to seem a bit inconsistent
>> to me.
>>
>> In the api index and show responses we handle has_many and belongs_to
>> relationships differently. Using rabl terminology, has_many associations
>> are modeled as child nodes with very limited fields (defined in
>> base.json.rabl) while belongs_to associations are modeled as first-level
>> attributes.
>>
>> Example to make it clear:
>> {
>> # belongs to operating system
>> "operatingsystem_id" => 7,
>> "operatingsystem_name" => "Rhel 6.3",
>>
>> # has many organizations
>> "organizations" => [
>> [0] {
>> "id" => 1,
>> "name" => "ACME_Corporation",
>> "title" => "ACME_Corporation"
>> }
>> ]
>> }
>>
>> I know the decision to model it this way has been made based on some
>> discussion and it also seemed quite fine to me until I started working
>> with it. After playing with the api when implementing associated
>> resources for hammer, I find child nodes and the possibility to add more
>> fields than name and id extremely handy.
>>
>> In many cases it is useful to display additional information with the
>> association to help user get oriented (e.g. subnet's net address,
>> template's kind, smart proxy's url). It is of course possible to
>> retrieve the desired information by performing additional gets to
>> appropriate resources but it's a bit annoying. Another benefit is
>> consistency and ease of use when you can treat both types of
>> associations equally.
>>
>> My proposal is to turn all associations into child nodes displaying
>> resource's base.json.rabl view.
>> What do you think?
>>
>> Regards
>> Tomas
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
For sub-resources we could use an "expansion" pattern. It would look something like this:
Given system 1234 that has_many subscriptions,
- GET /katello/api/v2/system/1234
- GET /katello/api/v2/system/1234?expand=subscriptions
- GET /katello/api/v2/system/1234?expand=all
And the resultant JSON would only include the subscriptions in the second and third examples.
That way the API calls that may not care about the expanded resources will be faster and the UI can still easily get what it needs to display a page.
Cheers,
Walden
···
----- Original Message -----
From: "Joseph Magen"
To: foreman-dev@googlegroups.com
Sent: Thursday, July 3, 2014 5:29:39 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
Hi Tomas,
Just checking back if there was a resolution on this issue.
Joseph
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
belongs to operating system
“operatingsystem_id” => 7,
“operatingsystem_name” => “Rhel 6.3”,
has many organizations
“organizations” => [
[0] {
“id” => 1,
“name” => “ACME_Corporation”,
“title” => “ACME_Corporation”
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups “foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
> Hi Tomas,
>
> Just checking back if there was a resolution on this issue.
>
> Joseph
>
I don't think we've come to any official resolution. For the sake of
consistency I'd prefer to use child nodes (pointing to the resource's
main.json.rabl) for both single references and collections.
T.
···
On 07/03/2014 11:29 AM, Joseph Magen wrote:
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
I think the main issue is: Make it consistent in the json, so either nested or flattened by not both. Furthermore, I am against an option that gives one or the other; what's the value of that to anyone over us just being consistent and documenting it?
This should be less of a discussion and more of a redmine issue that is on the immediate backlog for the full foretello dev team. Is there a ticket for this? Without this fixed I don't see how a version of the API can be labeled as "released and supported".
···
----- Original Message -----
> On 04/23/2014 05:21 PM, Joseph Magen wrote:
> > Tomas,
> >
> > Both are fine. It's a matter of preference. I don't know of a standard
> > "best practice" to display belongs_to associations in the root node or in
> > a child node.
> >
> > I think easier in a collection of objects (ex. hosts) to show the _name
> > fields in the root node like we're doing it, but I understand your point.
> >
> > {
> > "name": "fdev2.examplecom",
> > "id": 394,
> > "environment_id": 1,
> > "environment_name": "production",
> >
> > I'm open to either way. Maybe the best option is to have an option to show
> > belongs_to in the root or as child nodes.
> >
> > Joseph
>
> The difference between the approaches as I see it is in the efforts
> needed for providing additional information.
>
> We currently send only names and ids. I think it sometimes make sense to
> add more fields. If we wanted to display let's say addresses for
> associated subnets (we do that for has_many), we'd end up with:
>
> subent_id: ...
> subent_name: ...
> subnet_network_address: ...
>
> I agree the formatting (prefixing vs. nesting) is matter of preference.
>
> What I see as more important is that nesting and re-using base.json.rabl
> templates of referenced resources gives us more flexibility. You add
> field to the base template and it appears everywhere. At the moment we
> have all *_name and *_id for belongs_to associations "hardcoded" and
> distributed across all templates.
>
> I' totally fine with making it optional (per request). I'm not sure how
> difficult it would be to implement it though.
>
> Regards
> Tomas
>
> >
> >
> >
> > ----- Original Message -----
> >> From: "Tomas Strachota"
> >> To: foreman-dev@googlegroups.com
> >> Sent: Tuesday, April 22, 2014 6:31:47 PM
> >> Subject: [foreman-dev] api v2 - displaying associations in json responses
> >>
> >> Hello,
> >> I came across an api v2 feature that started to seem a bit inconsistent
> >> to me.
> >>
> >> In the api index and show responses we handle has_many and belongs_to
> >> relationships differently. Using rabl terminology, has_many associations
> >> are modeled as child nodes with very limited fields (defined in
> >> base.json.rabl) while belongs_to associations are modeled as first-level
> >> attributes.
> >>
> >> Example to make it clear:
> >> {
> >> # belongs to operating system
> >> "operatingsystem_id" => 7,
> >> "operatingsystem_name" => "Rhel 6.3",
> >>
> >> # has many organizations
> >> "organizations" => [
> >> [0] {
> >> "id" => 1,
> >> "name" => "ACME_Corporation",
> >> "title" => "ACME_Corporation"
> >> }
> >> ]
> >> }
> >>
> >> I know the decision to model it this way has been made based on some
> >> discussion and it also seemed quite fine to me until I started working
> >> with it. After playing with the api when implementing associated
> >> resources for hammer, I find child nodes and the possibility to add more
> >> fields than name and id extremely handy.
> >>
> >> In many cases it is useful to display additional information with the
> >> association to help user get oriented (e.g. subnet's net address,
> >> template's kind, smart proxy's url). It is of course possible to
> >> retrieve the desired information by performing additional gets to
> >> appropriate resources but it's a bit annoying. Another benefit is
> >> consistency and ease of use when you can treat both types of
> >> associations equally.
> >>
> >> My proposal is to turn all associations into child nodes displaying
> >> resource's base.json.rabl view.
> >> What do you think?
> >>
> >> Regards
> >> Tomas
> >>
> >> --
> >> You received this message because you are subscribed to the Google Groups
> >> "foreman-dev" group.
> >> To unsubscribe from this group and stop receiving emails from it, send an
> >> email to foreman-dev+unsubscribe@googlegroups.com.
> >> For more options, visit https://groups.google.com/d/optout.
> >>
> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
>
>
> > > Tomas,
> > >
> > > Both are fine. It's a matter of preference. I don't know of a standard
> > > "best practice" to display belongs_to associations in the root node or in
> > > a child node.
> > >
> > > I think easier in a collection of objects (ex. hosts) to show the _name
> > > fields in the root node like we're doing it, but I understand your point.
> > >
> > > {
> > > "name": "fdev2.examplecom",
> > > "id": 394,
> > > "environment_id": 1,
> > > "environment_name": "production",
> > >
> > > I'm open to either way. Maybe the best option is to have an option to
> > > show
> > > belongs_to in the root or as child nodes.
> > >
> > > Joseph
> >
> > The difference between the approaches as I see it is in the efforts
> > needed for providing additional information.
> >
> > We currently send only names and ids. I think it sometimes make sense to
> > add more fields. If we wanted to display let's say addresses for
> > associated subnets (we do that for has_many), we'd end up with:
> >
> > subent_id: …
> > subent_name: …
> > subnet_network_address: …
> >
> > I agree the formatting (prefixing vs. nesting) is matter of preference.
> >
> > What I see as more important is that nesting and re-using base.json.rabl
> > templates of referenced resources gives us more flexibility. You add
> > field to the base template and it appears everywhere. At the moment we
> > have all *_name and *_id for belongs_to associations "hardcoded" and
> > distributed across all templates.
> >
> > I' totally fine with making it optional (per request). I'm not sure how
> > difficult it would be to implement it though.
> >
> > Regards
> > Tomas
> >
> > >
> > >
> > >
> > >> From: "Tomas Strachota" <tstrachota@redhat.com>
> > >> To: foreman-dev@googlegroups.com
> > >> Sent: Tuesday, April 22, 2014 6:31:47 PM
> > >> Subject: [foreman-dev] api v2 - displaying associations in json
> > >> responses
> > >>
> > >> Hello,
> > >> I came across an api v2 feature that started to seem a bit inconsistent
> > >> to me.
> > >>
> > >> In the api index and show responses we handle has_many and belongs_to
> > >> relationships differently. Using rabl terminology, has_many associations
> > >> are modeled as child nodes with very limited fields (defined in
> > >> base.json.rabl) while belongs_to associations are modeled as first-level
> > >> attributes.
> > >>
> > >> Example to make it clear:
> > >> {
> > >> # belongs to operating system
> > >> "operatingsystem_id" => 7,
> > >> "operatingsystem_name" => "Rhel 6.3",
> > >>
> > >> # has many organizations
> > >> "organizations" => [
> > >> [0] {
> > >> "id" => 1,
> > >> "name" => "ACME_Corporation",
> > >> "title" => "ACME_Corporation"
> > >> }
> > >> ]
> > >> }
> > >>
> > >> I know the decision to model it this way has been made based on some
> > >> discussion and it also seemed quite fine to me until I started working
> > >> with it. After playing with the api when implementing associated
> > >> resources for hammer, I find child nodes and the possibility to add more
> > >> fields than name and id extremely handy.
> > >>
> > >> In many cases it is useful to display additional information with the
> > >> association to help user get oriented (e.g. subnet's net address,
> > >> template's kind, smart proxy's url). It is of course possible to
> > >> retrieve the desired information by performing additional gets to
> > >> appropriate resources but it's a bit annoying. Another benefit is
> > >> consistency and ease of use when you can treat both types of
> > >> associations equally.
> > >>
> > >> My proposal is to turn all associations into child nodes displaying
> > >> resource's base.json.rabl view.
> > >> What do you think?
> > >>
> > >> Regards
> > >> Tomas
> > >>
> > >> –
> > >> You received this message because you are subscribed to the Google
> > >> Groups
> > >> "foreman-dev" group.
> > >> To unsubscribe from this group and stop receiving emails from it, send
> > >> an
> > >> email to foreman-dev+unsubscribe@googlegroups.com.
> > >> For more options, visit https://groups.google.com/d/optout.
> > >>
> > >
> >
> > –
> > You received this message because you are subscribed to the Google Groups
> > "foreman-dev" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to foreman-dev+unsubscribe@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
> >
>
> I think the main issue is: Make it consistent in the json, so either nested
> or flattened by not both. Furthermore, I am against an option that gives one
> or the other; what's the value of that to anyone over us just being
> consistent and documenting it?
I agree with Tom here. Our JSON structure should be as static as possible because it makes moving parts less complicated. As long as the location of the data is documented (and returned consistently), there is no need of an option.
>
> This should be less of a discussion and more of a redmine issue that is on
> the immediate backlog for the full foretello dev team. Is there a ticket for
> this? Without this fixed I don't see how a version of the API can be labeled
> as "released and supported".
This does need to be fixed very quickly, otherwise I wouldn't consider our API completed and ready for widespread use.
···
----- Original Message -----
> ----- Original Message -----
> > On 04/23/2014 05:21 PM, Joseph Magen wrote:
> > > ----- Original Message -----
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
base.json.rabl usually contains only most basic attributes like :id and
:name e.g. for architecture. But it can differ for other resources as
needed.
···
On 28.04.14 10:25, Ohad Levy wrote:
> does this mean that we always include belongs_to attributes in the
> default show action?
>
> e.g. host would be something like:
>
> {
> name: ..
> ip: ..
> operatingsystem: {
> id:
> name:
> major:
> ..
> },
> compute_resource : {
> }
> architecture: { .. }
> }
>
> or is it an option to "expand" upon request?
>
> Ohad
>
>
>
> On Mon, Apr 28, 2014 at 11:14 AM, Petr Chalupa wrote:
>> +10 rendering belongs_to with base.json.rabl
>>
>> It's simpler, more consistent, and reuses template (less code to maintain).
>>
>>
>> On 22.04.14 17:31, Tomas Strachota wrote:
>>>
>>> Hello,
>>> I came across an api v2 feature that started to seem a bit inconsistent
>>> to me.
>>>
>>> In the api index and show responses we handle has_many and belongs_to
>>> relationships differently. Using rabl terminology, has_many associations
>>> are modeled as child nodes with very limited fields (defined in
>>> base.json.rabl) while belongs_to associations are modeled as first-level
>>> attributes.
>>>
>>> Example to make it clear:
>>> {
>>> # belongs to operating system
>>> "operatingsystem_id" => 7,
>>> "operatingsystem_name" => "Rhel 6.3",
>>>
>>> # has many organizations
>>> "organizations" => [
>>> [0] {
>>> "id" => 1,
>>> "name" => "ACME_Corporation",
>>> "title" => "ACME_Corporation"
>>> }
>>> ]
>>> }
>>>
>>> I know the decision to model it this way has been made based on some
>>> discussion and it also seemed quite fine to me until I started working
>>> with it. After playing with the api when implementing associated
>>> resources for hammer, I find child nodes and the possibility to add more
>>> fields than name and id extremely handy.
>>>
>>> In many cases it is useful to display additional information with the
>>> association to help user get oriented (e.g. subnet's net address,
>>> template's kind, smart proxy's url). It is of course possible to
>>> retrieve the desired information by performing additional gets to
>>> appropriate resources but it's a bit annoying. Another benefit is
>>> consistency and ease of use when you can treat both types of
>>> associations equally.
>>>
>>> My proposal is to turn all associations into child nodes displaying
>>> resource's base.json.rabl view.
>>> What do you think?
>>>
>>> Regards
>>> Tomas
>>>
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "foreman-dev" group.
>> To unsubscribe from this group and stop receiving emails from it, send an
>> email to foreman-dev+unsubscribe@googlegroups.com.
>> For more options, visit https://groups.google.com/d/optout.
>
> base.json.rabl usually contains only most basic attributes like :id and
> :name e.g. for architecture. But it can differ for other resources as
> needed.
indeed, my main concern is that you would make 20 SQL queries vs 1 or 2.
however, the current situation does the same as well. (with obj_id and obj_name)
···
On Mon, Apr 28, 2014 at 11:36 AM, Petr Chalupa wrote:
>
>
> On 28.04.14 10:25, Ohad Levy wrote:
>>
>> does this mean that we always include belongs_to attributes in the
>> default show action?
>>
>> e.g. host would be something like:
>>
>> {
>> name: ..
>> ip: ..
>> operatingsystem: {
>> id:
>> name:
>> major:
>> ..
>> },
>> compute_resource : {
>> }
>> architecture: { .. }
>> }
>>
>> or is it an option to "expand" upon request?
>>
>> Ohad
>>
>>
>>
>> On Mon, Apr 28, 2014 at 11:14 AM, Petr Chalupa >> wrote:
>>>
>>> +10 rendering belongs_to with base.json.rabl
>>>
>>> It's simpler, more consistent, and reuses template (less code to
>>> maintain).
>>>
>>>
>>> On 22.04.14 17:31, Tomas Strachota wrote:
>>>>
>>>>
>>>> Hello,
>>>> I came across an api v2 feature that started to seem a bit inconsistent
>>>> to me.
>>>>
>>>> In the api index and show responses we handle has_many and belongs_to
>>>> relationships differently. Using rabl terminology, has_many associations
>>>> are modeled as child nodes with very limited fields (defined in
>>>> base.json.rabl) while belongs_to associations are modeled as first-level
>>>> attributes.
>>>>
>>>> Example to make it clear:
>>>> {
>>>> # belongs to operating system
>>>> "operatingsystem_id" => 7,
>>>> "operatingsystem_name" => "Rhel 6.3",
>>>>
>>>> # has many organizations
>>>> "organizations" => [
>>>> [0] {
>>>> "id" => 1,
>>>> "name" => "ACME_Corporation",
>>>> "title" => "ACME_Corporation"
>>>> }
>>>> ]
>>>> }
>>>>
>>>> I know the decision to model it this way has been made based on some
>>>> discussion and it also seemed quite fine to me until I started working
>>>> with it. After playing with the api when implementing associated
>>>> resources for hammer, I find child nodes and the possibility to add more
>>>> fields than name and id extremely handy.
>>>>
>>>> In many cases it is useful to display additional information with the
>>>> association to help user get oriented (e.g. subnet's net address,
>>>> template's kind, smart proxy's url). It is of course possible to
>>>> retrieve the desired information by performing additional gets to
>>>> appropriate resources but it's a bit annoying. Another benefit is
>>>> consistency and ease of use when you can treat both types of
>>>> associations equally.
>>>>
>>>> My proposal is to turn all associations into child nodes displaying
>>>> resource's base.json.rabl view.
>>>> What do you think?
>>>>
>>>> Regards
>>>> Tomas
>>>>
>>>
>>> --
>>> You received this message because you are subscribed to the Google Groups
>>> "foreman-dev" group.
>>> To unsubscribe from this group and stop receiving emails from it, send an
>>> email to foreman-dev+unsubscribe@googlegroups.com.
>>> For more options, visit https://groups.google.com/d/optout.
>>
>>
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
See also the way Candlepin is doing it: http://www.candlepinproject.org/docs/candlepin/json_response_filtering.html which is quite similar to what I suggested in my last message.
Cheers,
Walden
···
----- Original Message -----
From: "Walden Raines"
To: foreman-dev@googlegroups.com
Sent: Thursday, July 3, 2014 9:26:45 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
For sub-resources we could use an “expansion” pattern. It would look something like this:
Given system 1234 that has_many subscriptions,
- GET /katello/api/v2/system/1234
- GET /katello/api/v2/system/1234?expand=subscriptions
- GET /katello/api/v2/system/1234?expand=all
And the resultant JSON would only include the subscriptions in the second and third examples.
That way the API calls that may not care about the expanded resources will be faster and the UI can still easily get what it needs to display a page.
Cheers,
Walden
----- Original Message -----
From: “Joseph Magen” jmagen@redhat.com
To: foreman-dev@googlegroups.com
Sent: Thursday, July 3, 2014 5:29:39 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
Hi Tomas,
Just checking back if there was a resolution on this issue.
Joseph
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
belongs to operating system
“operatingsystem_id” => 7,
“operatingsystem_name” => “Rhel 6.3”,
has many organizations
“organizations” => [
[0] {
“id” => 1,
“name” => “ACME_Corporation”,
“title” => “ACME_Corporation”
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups “foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups “foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
>> Hi Tomas,
>>
>> Just checking back if there was a resolution on this issue.
>>
>> Joseph
>>
>
> I don't think we've come to any official resolution. For the sake of
> consistency I'd prefer to use child nodes (pointing to the resource's
> main.json.rabl) for both single references and collections.
I meant pointing to base.json.rabl, sorry. That's our current practice.
···
On 07/08/2014 08:46 AM, Tomas Strachota wrote:
> On 07/03/2014 11:29 AM, Joseph Magen wrote:
T.
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json
responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google
Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it,
send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
>> base.json.rabl usually contains only most basic attributes like :id and
>> :name e.g. for architecture. But it can differ for other resources as
>> needed.
>
> indeed, my main concern is that you would make 20 SQL queries vs 1 or 2.
> however, the current situation does the same as well. (with obj_id and obj_name)
I think the number of SQL queries is fixable with
AResource.includes(:an_association_which_will_be_embedded_in_the_json_response)
···
On 28.04.14 10:51, Ohad Levy wrote:
> On Mon, Apr 28, 2014 at 11:36 AM, Petr Chalupa wrote:
On 28.04.14 10:25, Ohad Levy wrote:
does this mean that we always include belongs_to attributes in the
default show action?
e.g. host would be something like:
{
name: …
ip: …
operatingsystem: {
id:
name:
major:
…
},
compute_resource : {
}
architecture: { … }
}
or is it an option to “expand” upon request?
Ohad
On Mon, Apr 28, 2014 at 11:14 AM, Petr Chalupa pchalupa@redhat.com >>> wrote:
+10 rendering belongs_to with base.json.rabl
It’s simpler, more consistent, and reuses template (less code to
maintain).
On 22.04.14 17:31, Tomas Strachota wrote:
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Walden,
I agree, but the question is what is the default response. I would suggest for the show action to include most of the associations and user needs to be pass "exclude=". Like, for any "expensive" attributes/relationships that are not included by default, it makes sense that the user needs to pass the include/expand keyword to include them in the response.
Joseph
···
----- Original Message -----
> From: "Walden Raines"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 3, 2014 4:29:09 PM
> Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
>
> See also the way Candlepin is doing it:
> http://www.candlepinproject.org/docs/candlepin/json_response_filtering.html
> which is quite similar to what I suggested in my last message.
>
> Cheers,
> Walden
>
> ----- Original Message -----
> From: "Walden Raines"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 3, 2014 9:26:45 AM
> Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
>
> For sub-resources we could use an "expansion" pattern. It would look
> something like this:
>
> Given system 1234 that has_many subscriptions,
>
> 1. GET /katello/api/v2/system/1234
> 2. GET /katello/api/v2/system/1234?expand=subscriptions
> 3. GET /katello/api/v2/system/1234?expand=all
>
> And the resultant JSON would only include the subscriptions in the second and
> third examples.
>
> That way the API calls that may not care about the expanded resources will be
> faster and the UI can still easily get what it needs to display a page.
>
> Cheers,
> Walden
>
>
> ----- Original Message -----
> From: "Joseph Magen"
> To: foreman-dev@googlegroups.com
> Sent: Thursday, July 3, 2014 5:29:39 AM
> Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
>
> Hi Tomas,
>
> Just checking back if there was a resolution on this issue.
>
> Joseph
>
>
>
> ----- Original Message -----
> > From: "Tomas Strachota"
> > To: foreman-dev@googlegroups.com
> > Sent: Tuesday, April 22, 2014 6:31:47 PM
> > Subject: [foreman-dev] api v2 - displaying associations in json responses
> >
> > Hello,
> > I came across an api v2 feature that started to seem a bit inconsistent
> > to me.
> >
> > In the api index and show responses we handle has_many and belongs_to
> > relationships differently. Using rabl terminology, has_many associations
> > are modeled as child nodes with very limited fields (defined in
> > base.json.rabl) while belongs_to associations are modeled as first-level
> > attributes.
> >
> > Example to make it clear:
> > {
> > # belongs to operating system
> > "operatingsystem_id" => 7,
> > "operatingsystem_name" => "Rhel 6.3",
> >
> > # has many organizations
> > "organizations" => [
> > [0] {
> > "id" => 1,
> > "name" => "ACME_Corporation",
> > "title" => "ACME_Corporation"
> > }
> > ]
> > }
> >
> > I know the decision to model it this way has been made based on some
> > discussion and it also seemed quite fine to me until I started working
> > with it. After playing with the api when implementing associated
> > resources for hammer, I find child nodes and the possibility to add more
> > fields than name and id extremely handy.
> >
> > In many cases it is useful to display additional information with the
> > association to help user get oriented (e.g. subnet's net address,
> > template's kind, smart proxy's url). It is of course possible to
> > retrieve the desired information by performing additional gets to
> > appropriate resources but it's a bit annoying. Another benefit is
> > consistency and ease of use when you can treat both types of
> > associations equally.
> >
> > My proposal is to turn all associations into child nodes displaying
> > resource's base.json.rabl view.
> > What do you think?
> >
> > Regards
> > Tomas
> >
> > --
> > You received this message because you are subscribed to the Google Groups
> > "foreman-dev" group.
> > To unsubscribe from this group and stop receiving emails from it, send an
> > email to foreman-dev+unsubscribe@googlegroups.com.
> > For more options, visit https://groups.google.com/d/optout.
> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
I am fine with rendering child nodes using 'base.json.rabl'. I assume it helps you with hammer development.
Since v2 can still have breaking changes, do we have the green light to change this across the board? @ohad, @dominic
As a summary so we are all on the same page, this
{
"name": "fdev2.sat.lab.tlv.redhat.com",
"id": 394,
"environment_id": 1,
"environment_name": "production",
"domain_id": 6,
"domain_name": "sat.lab.tlv.redhat.com",
"operatingsystem_id": 42,
"operatingsystem_name": "CentOS 6.4",
…
…
}
becomes this
{
"name": "fdev2.sat.lab.tlv.redhat.com",
"id": 394,
"environment": {
"name": "production",
"id": 1
},
"domain": {
"id": 6,
"name": "sat.lab.tlv.redhat.com"
},
"operatingsystem": {
"id": 42,
"name": "CentOS",
"fullname": "CentOS 6.4"
},
Note, that operatingsystem.name is different than operatingsystem_name. This happens when we manually assigned attr_name :to_label (that's not :name)
Regards,
Joseph
···
----- Original Message -----
> From: "Tomas Strachota"
> To: foreman-dev@googlegroups.com
> Sent: Tuesday, July 8, 2014 9:49:53 AM
> Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
>
> On 07/08/2014 08:46 AM, Tomas Strachota wrote:
> > On 07/03/2014 11:29 AM, Joseph Magen wrote:
> >> Hi Tomas,
> >>
> >> Just checking back if there was a resolution on this issue.
> >>
> >> Joseph
> >>
> >
> > I don't think we've come to any official resolution. For the sake of
> > consistency I'd prefer to use child nodes (pointing to the resource's
> > main.json.rabl) for both single references and collections.
>
> I meant pointing to base.json.rabl, sorry. That's our current practice.
>
> >
> > T.
> >
> >>
> >>
> >> ----- Original Message -----
> >>> From: "Tomas Strachota"
> >>> To: foreman-dev@googlegroups.com
> >>> Sent: Tuesday, April 22, 2014 6:31:47 PM
> >>> Subject: [foreman-dev] api v2 - displaying associations in json
> >>> responses
> >>>
> >>> Hello,
> >>> I came across an api v2 feature that started to seem a bit inconsistent
> >>> to me.
> >>>
> >>> In the api index and show responses we handle has_many and belongs_to
> >>> relationships differently. Using rabl terminology, has_many associations
> >>> are modeled as child nodes with very limited fields (defined in
> >>> base.json.rabl) while belongs_to associations are modeled as first-level
> >>> attributes.
> >>>
> >>> Example to make it clear:
> >>> {
> >>> # belongs to operating system
> >>> "operatingsystem_id" => 7,
> >>> "operatingsystem_name" => "Rhel 6.3",
> >>>
> >>> # has many organizations
> >>> "organizations" => [
> >>> [0] {
> >>> "id" => 1,
> >>> "name" => "ACME_Corporation",
> >>> "title" => "ACME_Corporation"
> >>> }
> >>> ]
> >>> }
> >>>
> >>> I know the decision to model it this way has been made based on some
> >>> discussion and it also seemed quite fine to me until I started working
> >>> with it. After playing with the api when implementing associated
> >>> resources for hammer, I find child nodes and the possibility to add more
> >>> fields than name and id extremely handy.
> >>>
> >>> In many cases it is useful to display additional information with the
> >>> association to help user get oriented (e.g. subnet's net address,
> >>> template's kind, smart proxy's url). It is of course possible to
> >>> retrieve the desired information by performing additional gets to
> >>> appropriate resources but it's a bit annoying. Another benefit is
> >>> consistency and ease of use when you can treat both types of
> >>> associations equally.
> >>>
> >>> My proposal is to turn all associations into child nodes displaying
> >>> resource's base.json.rabl view.
> >>> What do you think?
> >>>
> >>> Regards
> >>> Tomas
> >>>
> >>> --
> >>> You received this message because you are subscribed to the Google
> >>> Groups
> >>> "foreman-dev" group.
> >>> To unsubscribe from this group and stop receiving emails from it,
> >>> send an
> >>> email to foreman-dev+unsubscribe@googlegroups.com.
> >>> For more options, visit https://groups.google.com/d/optout.
> >>>
> >>
> >
>
> --
> You received this message because you are subscribed to the Google Groups
> "foreman-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to foreman-dev+unsubscribe@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.
>
> I am fine with rendering child nodes using 'base.json.rabl'. I assume it helps you with hammer development.
Yes, we'll be able to use same formatters for singles and collections. I
also find it more flexible when you need to pass additional details with
the association.
I expect switching between the versions on the Hammer side to be smooth.
> Since v2 can still have breaking changes, do we have the green light to change this across the board? @ohad, @dominic
>
> As a summary so we are all on the same page, this
>
> {
> "name": "fdev2.sat.lab.tlv.redhat.com",
> "id": 394,
> "environment_id": 1,
> "environment_name": "production",
> "domain_id": 6,
> "domain_name": "sat.lab.tlv.redhat.com",
> "operatingsystem_id": 42,
> "operatingsystem_name": "CentOS 6.4",
> …
> …
> }
>
> becomes this
>
> {
> "name": "fdev2.sat.lab.tlv.redhat.com",
> "id": 394,
> "environment": {
> "name": "production",
> "id": 1
> },
> "domain": {
> "id": 6,
> "name": "sat.lab.tlv.redhat.com"
> },
> "operatingsystem": {
> "id": 42,
> "name": "CentOS",
> "fullname": "CentOS 6.4"
> },
>
+1
···
On 07/08/2014 09:00 AM, Joseph Magen wrote:
Note, that operatingsystem.name is different than operatingsystem_name. This happens when we manually assigned attr_name :to_label (that’s not :name)
Regards,
Joseph
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, July 8, 2014 9:49:53 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
On 07/08/2014 08:46 AM, Tomas Strachota wrote:
On 07/03/2014 11:29 AM, Joseph Magen wrote:
Hi Tomas,
Just checking back if there was a resolution on this issue.
Joseph
I don’t think we’ve come to any official resolution. For the sake of
consistency I’d prefer to use child nodes (pointing to the resource’s
main.json.rabl) for both single references and collections.
I meant pointing to base.json.rabl, sorry. That’s our current practice.
T.
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json
responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google
Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it,
send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
That new JSON is an improvement and similar to every other REST API I've seen, +1.
With regard to the expansion idea, we need to figure out a rubric for how to determine if something is an expansion or included in the base JSON. Ideally this would be intuitive to the user, not "well it's an expensive call, let's just make it an expansion". I can see why others have gone with making all relations expansions as it is more straightforward to the user.
I think that everything has a one to many or many to many relationship ought to be an expansion but simple one to one associations can be part of the base object. What do y'all think?
Cheers,
Walden
···
----- Original Message -----
From: "Joseph Magen"
To: foreman-dev@googlegroups.com
Sent: Tuesday, July 8, 2014 3:00:57 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
I am fine with rendering child nodes using ‘base.json.rabl’. I assume it helps you with hammer development.
Since v2 can still have breaking changes, do we have the green light to change this across the board? @ohad, @dominic
As a summary so we are all on the same page, this
{
“name”: “fdev2.sat.lab.tlv.redhat.com”,
“id”: 394,
“environment_id”: 1,
“environment_name”: “production”,
“domain_id”: 6,
“domain_name”: “sat.lab.tlv.redhat.com”,
“operatingsystem_id”: 42,
“operatingsystem_name”: “CentOS 6.4”,
…
…
}
becomes this
{
“name”: “fdev2.sat.lab.tlv.redhat.com”,
“id”: 394,
“environment”: {
“name”: “production”,
“id”: 1
},
“domain”: {
“id”: 6,
“name”: “sat.lab.tlv.redhat.com”
},
“operatingsystem”: {
“id”: 42,
“name”: “CentOS”,
“fullname”: “CentOS 6.4”
},
Note, that operatingsystem.name is different than operatingsystem_name. This happens when we manually assigned attr_name :to_label (that’s not :name)
Regards,
Joseph
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, July 8, 2014 9:49:53 AM
Subject: Re: [foreman-dev] api v2 - displaying associations in json responses
On 07/08/2014 08:46 AM, Tomas Strachota wrote:
On 07/03/2014 11:29 AM, Joseph Magen wrote:
Hi Tomas,
Just checking back if there was a resolution on this issue.
Joseph
I don’t think we’ve come to any official resolution. For the sake of
consistency I’d prefer to use child nodes (pointing to the resource’s
main.json.rabl) for both single references and collections.
I meant pointing to base.json.rabl, sorry. That’s our current practice.
T.
----- Original Message -----
From: “Tomas Strachota” tstrachota@redhat.com
To: foreman-dev@googlegroups.com
Sent: Tuesday, April 22, 2014 6:31:47 PM
Subject: [foreman-dev] api v2 - displaying associations in json
responses
Hello,
I came across an api v2 feature that started to seem a bit inconsistent
to me.
In the api index and show responses we handle has_many and belongs_to
relationships differently. Using rabl terminology, has_many associations
are modeled as child nodes with very limited fields (defined in
base.json.rabl) while belongs_to associations are modeled as first-level
attributes.
Example to make it clear:
{
# belongs to operating system
"operatingsystem_id" => 7,
“operatingsystem_name” => “Rhel 6.3”,
# has many organizations
"organizations" => [
[0] {
"id" => 1,
"name" => "ACME_Corporation",
"title" => "ACME_Corporation"
}
]
}
I know the decision to model it this way has been made based on some
discussion and it also seemed quite fine to me until I started working
with it. After playing with the api when implementing associated
resources for hammer, I find child nodes and the possibility to add more
fields than name and id extremely handy.
In many cases it is useful to display additional information with the
association to help user get oriented (e.g. subnet’s net address,
template’s kind, smart proxy’s url). It is of course possible to
retrieve the desired information by performing additional gets to
appropriate resources but it’s a bit annoying. Another benefit is
consistency and ease of use when you can treat both types of
associations equally.
My proposal is to turn all associations into child nodes displaying
resource’s base.json.rabl view.
What do you think?
Regards
Tomas
–
You received this message because you are subscribed to the Google
Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it,
send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups
"foreman-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
–
You received this message because you are subscribed to the Google Groups “foreman-dev” group.
To unsubscribe from this group and stop receiving emails from it, send an email to foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
