API v2 JSON response root nodes

Development
#1

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!

#2

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! >
#3

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

#4

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.
#5

> 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.

#6

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.

#7

> 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.

#8

>
> > 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.

#9

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 >
#10

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.
#11

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