API v2 JSON response root nodes

Some more discussion has cropped up around root nodes in Foreman/Katello
JSON responses.

My preference was to have a default root-node for both single-object- and
collection-responses.

  • "result" node for single-object responses
  • "results" node for collection responses

I don't feel strongly that the JSON must be this way, but no one else
particularly stuck to their guns until after I made a decision.

DISCUSS!

To me, this seems at odds with the POST/PUT actions in the documentation.
For create/update, you are just sending the fields that you want to set or
update. I'd at least recommend being consistent across show, update, create.

··· On Friday, November 15, 2013 10:37:59 AM UTC-5, Adam Price wrote: > > Some more discussion has cropped up around root nodes in Foreman/Katello > JSON responses. > > My preference was to have a default root-node for both single-object- and > collection-responses. > > - "result" node for single-object responses > - "results" node for collection responses > > I don't feel strongly that the JSON must be this way, but no one else > particularly stuck to their guns until after I made a decision. > > DISCUSS! >

I have no opinion (or experience) as to whether it's "result(s)" or
named after the object type, but think it's important that the
collection versus single object responses are consistent. I dislike
having "results" for collection and "host" etc for single objects.

For the record, the discussions on PRs so far have occurred here:

https://github.com/theforeman/theforeman.org/pull/106#discussion_r7252476
https://github.com/theforeman/theforeman.org/pull/119#discussion_r7657572
https://github.com/theforeman/theforeman.org/pull/119#discussion_r7664044

And we have this PR open to change the collection response:

https://github.com/theforeman/foreman/pull/1010

And this issue for the single response (which I did thinking they'd be
consistent):

··· On 15/11/13 15:37, Adam Price wrote: > Some more discussion has cropped up around root nodes in Foreman/Katello > JSON responses. > > My preference was to have a default root-node for both single-object- > and collection-responses. > > - "result" node for single-object responses > - "results" node for collection responses > > I don't feel strongly that the JSON must be this way, but no one else > particularly stuck to their guns until after I made a decision. > > DISCUSS!


Dominic Cleal
Red Hat Engineering

So… do we have agreement on this?

Single objects are blank root nodes, except if you specify one? And,
collecitons have an envelope with metatdata, and a results sectin which
is the real data whose name can be overridden. Is that it?

And, I assume PUT/POST always returns the whole obejct (basically, the
GET call).

– bk

··· On 11/15/2013 10:37 AM, Adam Price wrote: > Some more discussion has cropped up around root nodes in Foreman/Katello > JSON responses. > > My preference was to have a default root-node for both single-object- > and collection-responses. > > - "result" node for single-object responses > - "results" node for collection responses > > I don't feel strongly that the JSON must be this way, but no one else > particularly stuck to their guns until after I made a decision. > > DISCUSS! > > -- > 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/groups/opt_out.

> To me, this seems at odds with the POST/PUT actions in the documentation.
> For create/update, you are just sending the fields that you want to set or
> update. I'd at least recommend being consistent across show, update, create.

+1 This consistency seems more improtant to me than index vs. show

– Ivan

··· ----- Original Message -----

On Friday, November 15, 2013 10:37:59 AM UTC-5, Adam Price wrote:

Some more discussion has cropped up around root nodes in Foreman/Katello
JSON responses.

My preference was to have a default root-node for both single-object- and
collection-responses.

  • “result” node for single-object responses
  • “results” node for collection responses

I don’t feel strongly that the JSON must be this way, but no one else
particularly stuck to their guns until after I made a decision.

DISCUSS!


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/groups/opt_out.

The pull request that generated this discussion got merged earlier today.
Not sure why given the open discussion.

David

··· On Tue, Nov 19, 2013 at 3:22 PM, Bryan Kearney wrote:

On 11/15/2013 10:37 AM, Adam Price wrote:

Some more discussion has cropped up around root nodes in Foreman/Katello
JSON responses.

My preference was to have a default root-node for both single-object-
and collection-responses.

  • “result” node for single-object responses
  • “results” node for collection responses

I don’t feel strongly that the JSON must be this way, but no one else
particularly stuck to their guns until after I made a decision.

DISCUSS!


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/groups/opt_out.

So… do we have agreement on this?

Single objects are blank root nodes, except if you specify one? And,
collecitons have an envelope with metatdata, and a results sectin which is
the real data whose name can be overridden. Is that it?

And, I assume PUT/POST always returns the whole obejct (basically, the GET
call).

– bk


You received this message because you are subscribed to a topic in the
Google Groups “foreman-dev” group.
To unsubscribe from this topic, visit https://groups.google.com/d/
topic/foreman-dev/Z8FFDQ9prG0/unsubscribe.
To unsubscribe from this group and all its topics, send an email to
foreman-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

> From: "Bryan Kearney" <bryan.kearney@gmail.com>
> To: foreman-dev@googlegroups.com
> Sent: Tuesday, November 19, 2013 10:22:25 PM
> Subject: Re: [foreman-dev] API v2 JSON response root nodes
>
> > Some more discussion has cropped up around root nodes in Foreman/Katello
> > JSON responses.
> >
> > My preference was to have a default root-node for both single-object-
> > and collection-responses.
> >
> > - "result" node for single-object responses
> > - "results" node for collection responses
> >
> > I don't feel strongly that the JSON must be this way, but no one else
> > particularly stuck to their guns until after I made a decision.
> >
> > DISCUSS!
> >
> > –
> > 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/groups/opt_out.
> So… do we have agreement on this?
>
> Single objects are blank root nodes, except if you specify one?

Yes, a node can be added/specified by passing ?object_root= (this may change to ?root_name= in the future, I'm checking on same side effects)

> collecitons have an envelope with metatdata, and a results sectin which
> is the real data whose name can be overridden. Is that it?

Yes, node is 'results' and can be override by ?root_name=

>
> And, I assume PUT/POST always returns the whole obejct (basically, the
> GET call).

Yes, it returns the GET call, but it may or may not be the whole object.

··· ----- Original Message ----- > On 11/15/2013 10:37 AM, Adam Price wrote:

– bk


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/groups/opt_out.

>
> > To me, this seems at odds with the POST/PUT actions in the
> documentation.
> > For create/update, you are just sending the fields that you want to set
> or
> > update. I'd at least recommend being consistent across show, update,
> create.
>
> +1 This consistency seems more improtant to me than index vs. show
>
> – Ivan
>

Oooops, you're right. this is inconsistent. i vote for consistency across
POST/PUT actions as well.

Need to change the documentation to reflect that.

··· > ----- Original Message -----

On Friday, November 15, 2013 10:37:59 AM UTC-5, Adam Price wrote:

Some more discussion has cropped up around root nodes in
Foreman/Katello

JSON responses.

My preference was to have a default root-node for both single-object-
and

collection-responses.

  • “result” node for single-object responses
  • “results” node for collection responses

I don’t feel strongly that the JSON must be this way, but no one else
particularly stuck to their guns until after I made a decision.

DISCUSS!


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...@googlegroups.com <javascript:>.
For more options, visit https://groups.google.com/groups/opt_out.

I am less concerned about that… as I we can update the docs. I am more
interesed in getting some of hte katello engine bits moved to the
correct format. This is blocking htat.

– bk

··· On 11/19/2013 04:00 PM, David Davis wrote: > The pull request that generated this discussion got merged earlier > today. Not sure why given the open discussion. > > > David >

ok… so PUT returns only what it gets?

Adam… does this unblock you?
– bk

··· On 11/20/2013 02:43 AM, Joseph Magen wrote: > ----- Original Message ----- >> From: "Bryan Kearney" >> To: foreman-dev@googlegroups.com >> Sent: Tuesday, November 19, 2013 10:22:25 PM >> Subject: Re: [foreman-dev] API v2 JSON response root nodes >> >> On 11/15/2013 10:37 AM, Adam Price wrote: >>> Some more discussion has cropped up around root nodes in Foreman/Katello >>> JSON responses. >>> >>> My preference was to have a default root-node for both single-object- >>> and collection-responses. >>> >>> - "result" node for single-object responses >>> - "results" node for collection responses >>> >>> I don't feel strongly that the JSON must be this way, but no one else >>> particularly stuck to their guns until after I made a decision. >>> >>> DISCUSS! >>> >>> -- >>> 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/groups/opt_out. >> So.. do we have agreement on this? >> >> Single objects are blank root nodes, except if you specify one? > > Yes, a node can be added/specified by passing ?object_root= (this may change to ?root_name= in the future, I'm checking on same side effects) > >> collecitons have an envelope with metatdata, and a results sectin which >> is the real data whose name can be overridden. Is that it? > > Yes, node is 'results' and can be override by ?root_name= > >> >> And, I assume PUT/POST always returns the whole obejct (basically, the >> GET call). > > Yes, it returns the GET call, but it may or may **not** be the **whole** object.

this is good for me to keep working.

··· ----- Original Message ----- > From: "Bryan Kearney" > To: foreman-dev@googlegroups.com > Sent: Wednesday, November 20, 2013 8:10:25 AM > Subject: Re: [foreman-dev] API v2 JSON response root nodes > > On 11/20/2013 02:43 AM, Joseph Magen wrote: > > ----- Original Message ----- > >> From: "Bryan Kearney" > >> To: foreman-dev@googlegroups.com > >> Sent: Tuesday, November 19, 2013 10:22:25 PM > >> Subject: Re: [foreman-dev] API v2 JSON response root nodes > >> > >> On 11/15/2013 10:37 AM, Adam Price wrote: > >>> Some more discussion has cropped up around root nodes in Foreman/Katello > >>> JSON responses. > >>> > >>> My preference was to have a default root-node for both single-object- > >>> and collection-responses. > >>> > >>> - "result" node for single-object responses > >>> - "results" node for collection responses > >>> > >>> I don't feel strongly that the JSON must be this way, but no one else > >>> particularly stuck to their guns until after I made a decision. > >>> > >>> DISCUSS! > >>> > >>> -- > >>> 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/groups/opt_out. > >> So.. do we have agreement on this? > >> > >> Single objects are blank root nodes, except if you specify one? > > > > Yes, a node can be added/specified by passing ?object_root= (this may > > change to ?root_name= in the future, I'm checking on same side effects) > > > >> collecitons have an envelope with metatdata, and a results sectin which > >> is the real data whose name can be overridden. Is that it? > > > > Yes, node is 'results' and can be override by ?root_name= > > > >> > >> And, I assume PUT/POST always returns the whole obejct (basically, the > >> GET call). > > > > Yes, it returns the GET call, but it may or may **not** be the **whole** > > object. > > ok... so PUT returns only what it gets? > > Adam.. does this unblock you? > -- bk

  • adam price