Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2. I think this will be helpful for developers of the API as well as clients the consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing fields= or expand=)
  5. Default response for single objects (without explicity passing fields= or expand=)
  6. Customized Responses (fields=, expand=)
  7. Separate API routes for all nested resources
  8. Hypermedia HATEOS feaures
  9. Versioning

Feel free to add more topics or comment on existing one. In most cases, I think it's best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat

> Hi all,
>
> I started an etherpad so we can discuss some conventions for API v2. I think this will be helpful for developers of the API as well as clients the consume the Foreman & Katello APIs.
>
> http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2
>
> The initial topics are as follows:
>
> 1) JSON Response for Collections
> 2) JSON Response for Single Object
> 3) Meta Data for Pagination Collections
> 4) Default response for collections (without explicity passing fields= or expand=)
> 5) Default response for single objects (without explicity passing fields= or expand=)
> 6) Customized Responses (fields=, expand=)
> 7) Separate API routes for all nested resources
> 8) Hypermedia HATEOS feaures
> 9) Versioning
>
> Feel free to add more topics or comment on existing one. In most cases, I think it's best to write comments, +1, -1 on the etherpad.
Thanks for putting this together! Comments added.

Section about plugins extending API may be worth adding. I'm not sure
how that works yet, but we will need to deal with the extensions in API
bindings and Hammer. Anything to start with would be helpful.

Martin

··· On 08/19/2013 12:22 PM, Joseph Magen wrote:

Regards,
Joseph Magen
Red Hat

Here is a summary from the etherpad and internal discussion for the of the Foreman API v2 conventions.

We can continue the discussion here by email.

  1. Overview of rabl file structure/setup and URL override parameters
  • Three partials for each object
    1. base - minimal fields such as :id, :name and possibly more depending on object
    2. main - 'important' fields (varies depending on object)
    3. full - all fields in object
  • Option to override default fields by passing fields= as URL parameter
    1. fields=common-delimited list - Ex. api/hosts?fields=name,ip,mac,environment
    2. fields=full - return all fields
    3. fields=base - return base fields
  • Include time-stamps by default on 'main' and 'full' partials
  • If there is belong_to field (ex. environment), include _id and _name by default (ex. environment_id, environment_name)
  • Option to expand has_many (nested) relationships by passing expand= as URL parameter
  • For each expand= relationship, can include (option) in parentheses. options include:
    1. () nothing - 'base' fields by default. Ex. api/domains?expand=parameters
    2. (main) - 'main' fields Ex. api/domains?expand=parameters(main)
    3. (full) - 'full' fields Ex. api/domains?expand=parameters(full)
    4. (field list) - Ex. api/domains?expand=parameters(name,value)
    5. (ids) - same as passing *_ids attribute into fields= Ex. api/domains?expand=parameters(ids)
    6. (names) - same as passing *_names attribute into fields= Ex. api/domains?expand=parameters(names)
  1. JSON Response for Collections

Node Name:

  • default collection root node name is 'results'
  • option to change default to controller_name (ex. domains, environments, etc) in rabl_init.rb
  • option to manually pass root_name as URL parameter (e.x. /api/domains?root_name=data
  • option to remove root node by passing root_name=false (e.x. /api/domains?root_name=false)

Response Fields:

  • show 'main' fields by default for collection
  • do not show has_many (nested) relationships by default
  • override default by passing fields=, expand=relationship(option)
  1. JSON Response for Individual Object

Node Name:

  • default object root node name is 'object name' (ex. domain, environment, etc)
  • option to manually pass object_name as URL parameter (e.x. /api/domains/11?object_name=record)
  • option to remove object root node by passing object_name=false (e.x. /api/domains/11?object_name=false)

Response Fields:

  • show 'full' fields by default for individual object
  • do not show has_many (nested) relationships by default
  • override default by passing fields=, expand=relationship(option)
  1. Meta Data for Pagination Collections
  • metadata added by default on collections
  • attribute names of metadata still to be determined: total, subtotal, limit, offset, page, per_page, search, sort, etc
  1. Nested API routes (ex. GET /api/domains/5/subnets)
  • Nested routes for :index, :show, and :create operations (only when needed)
  • Use root-level resources for :update and :destroy (where there's an id)
  1. Versioning
  • to be discussed further
  1. Hypermedia HATEOS feaures
  • not for v2
  • possibly will be implemented later

More discussion and comments is welcomed.

Regards,

Joseph Magen
Red Hat

··· ----- Original Message ----- From: "Joseph Magen" To: "katello-devel" Sent: Monday, August 19, 2013 1:23:36 PM Subject: Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2. I think this will be helpful for developers of the API as well as clients the consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing fields= or expand=)
  5. Default response for single objects (without explicity passing fields= or expand=)
  6. Customized Responses (fields=, expand=)
  7. Separate API routes for all nested resources
  8. Hypermedia HATEOS feaures
  9. Versioning

Feel free to add more topics or comment on existing one. In most cases, I think it’s best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat


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.

What was decided for POST creation of new objects in v2, nested in resource
or root level?

POST /something {something: {name:foo, value:123}}

or

POST /something {name:foo, value:123}

Re-sending (I sent it the wrong katello-devel address)

··· -------- Here is a summary from the etherpad and internal discussion for the of the Foreman API v2 conventions.

We can continue the discussion here by email.

  1. Overview of rabl file structure/setup and URL override parameters
  • Three partials for each object
    1. base - minimal fields such as :id, :name and possibly more depending on object
    2. main - ‘important’ fields (varies depending on object)
    3. full - all fields in object
  • Option to override default fields by passing fields= as URL parameter
    1. fields=common-delimited list - Ex. api/hosts?fields=name,ip,mac,environment
    2. fields=full - return all fields
    3. fields=base - return base fields
  • Include time-stamps by default on ‘main’ and ‘full’ partials
  • If there is belong_to field (ex. environment), include _id and _name by default (ex. environment_id, environment_name)
  • Option to expand has_many (nested) relationships by passing expand= as URL parameter
  • For each expand= relationship, can include (option) in parentheses. options include:
    1. () nothing - ‘base’ fields by default. Ex. api/domains?expand=parameters
    2. (main) - ‘main’ fields Ex. api/domains?expand=parameters(main)
    3. (full) - ‘full’ fields Ex. api/domains?expand=parameters(full)
    4. (field list) - Ex. api/domains?expand=parameters(name,value)
    5. (ids) - same as passing *_ids attribute into fields= Ex. api/domains?expand=parameters(ids)
    6. (names) - same as passing *_names attribute into fields= Ex. api/domains?expand=parameters(names)
  1. JSON Response for Collections

Node Name:

  • default collection root node name is ‘results’
  • option to change default to controller_name (ex. domains, environments, etc) in rabl_init.rb
  • option to manually pass root_name as URL parameter (e.x. /api/domains?root_name=data
  • option to remove root node by passing root_name=false (e.x. /api/domains?root_name=false)

Response Fields:

  • show ‘main’ fields by default for collection
  • do not show has_many (nested) relationships by default
  • override default by passing fields=, expand=relationship(option)
  1. JSON Response for Individual Object

Node Name:

  • default object root node name is ‘object name’ (ex. domain, environment, etc)
  • option to manually pass object_name as URL parameter (e.x. /api/domains/11?object_name=record)
  • option to remove object root node by passing object_name=false (e.x. /api/domains/11?object_name=false)

Response Fields:

  • show ‘full’ fields by default for individual object
  • do not show has_many (nested) relationships by default
  • override default by passing fields=, expand=relationship(option)
  1. Meta Data for Pagination Collections
  • metadata added by default on collections
  • attribute names of metadata still to be determined: total, subtotal, limit, offset, page, per_page, search, sort, etc
  1. Nested API routes (ex. GET /api/domains/5/subnets)
  • Nested routes for :index, :show, and :create operations (only when needed)
  • Use root-level resources for :update and :destroy (where there’s an id)
  1. Versioning
  • to be discussed further
  1. Hypermedia HATEOS feaures
  • not for v2
  • possibly will be implemented later

More discussion and comments is welcomed.

Regards,

Joseph Magen
Red Hat

----- Original Message -----
From: “Joseph Magen” jmagen@redhat.com
To: “katello-devel” katello-devel@redhat.com
Sent: Monday, August 19, 2013 1:23:36 PM
Subject: Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2. I think this will be helpful for developers of the API as well as clients the consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing fields= or expand=)
  5. Default response for single objects (without explicity passing fields= or expand=)
  6. Customized Responses (fields=, expand=)
  7. Separate API routes for all nested resources
  8. Hypermedia HATEOS feaures
  9. Versioning

Feel free to add more topics or comment on existing one. In most cases, I think it’s best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat


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.

We decided that resources can also be created in the nested root as well.

Joseph

··· ----- Original Message ----- From: "Thomas McKay" To: foreman-dev@googlegroups.com Cc: katello-dev@googlegroups.com Sent: Friday, October 4, 2013 4:57:46 AM Subject: [foreman-dev] Re: Foreman & Katello API v2 Conventions - etherpad discussion

What was decided for POST creation of new objects in v2, nested in resource
or root level?

POST /something {something: {name:foo, value:123}}

or

POST /something {name:foo, value:123}


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.

> Re-sending (I sent it the wrong katello-devel address)
>
> --------
> Here is a summary from the etherpad and internal discussion for the of the Foreman API v2 conventions.
>
> We can continue the discussion here by email.
>
> 1) Overview of rabl file structure/setup and URL override parameters
>
> * Three partials for each object
> 1) base - minimal fields such as :id, :name and possibly more depending on object
> 2) main - 'important' fields (varies depending on object)
> 3) full - all fields in object
> * Option to override default fields by passing fields= as URL parameter
> 1) fields=common-delimited list - Ex. api/hosts?fields=name,ip,mac,environment
> 2) fields=full - return all fields
> 3) fields=base - return base fields
> * Include time-stamps by default on 'main' and 'full' partials
> * If there is belong_to field (ex. environment), include _id and _name by default (ex. environment_id, environment_name)
> * Option to expand has_many (nested) relationships by passing expand= as URL parameter
> * For each expand= relationship, can include (option) in parentheses. options include:
> 1) () nothing - 'base' fields by default. Ex. api/domains?expand=parameters
> 2) (main) - 'main' fields Ex. api/domains?expand=parameters(main)
> 3) (full) - 'full' fields Ex. api/domains?expand=parameters(full)
> 4) (field list) - Ex. api/domains?expand=parameters(name,value)
> 5) (ids) - same as passing *_ids attribute into fields= Ex. api/domains?expand=parameters(ids)
> 6) (names) - same as passing *_names attribute into fields= Ex. api/domains?expand=parameters(names)
>
>
> 2) JSON Response for Collections
>
> Node Name:
> * default collection root node name is 'results'
> * option to change default to controller_name (ex. domains, environments, etc) in rabl_init.rb
> * option to manually pass root_name as URL parameter (e.x. /api/domains?root_name=data
> * option to remove root node by passing root_name=false (e.x. /api/domains?root_name=false)
>
> Response Fields:
> * show 'main' fields by default for collection
> * do not show has_many (nested) relationships by default
> * override default by passing fields=, expand=relationship(option)
>
>
> 3) JSON Response for Individual Object
>
> Node Name:
> * default object root node name is 'object name' (ex. domain, environment, etc)
> * option to manually pass object_name as URL parameter (e.x. /api/domains/11?object_name=record)
> * option to remove object root node by passing object_name=false (e.x. /api/domains/11?object_name=false)
>
> Response Fields:
> * show 'full' fields by default for individual object
> * do not show has_many (nested) relationships by default
> * override default by passing fields=, expand=relationship(option)
>
>
> 4) Meta Data for Pagination Collections
>
> * metadata added by default on collections
> * attribute names of metadata still to be determined: total, subtotal, limit, offset, page, per_page, search, sort, etc
>
>
> 5) Nested API routes (ex. GET /api/domains/5/subnets)
> * Nested routes for :index, :show, and :create operations (only when needed)
> * Use root-level resources for :update and :destroy (where there's an id)

so this means to 'show' a subnet I would use GET /api/domains/5/subnets/3

but to delete I would use: DELETE /api/subnets/3 ?

To me this is quite confusing. Using different urls for delete/update
vs show/create makes it much more difficult/annoying to implement a
client to the apis.

I would prefer to see:

GET /api/subnets <- list all visible subnets
GET /api/subnets/3
POST /api/subnets
PUT /api/subnets/3
DELETE /api/subnets/3
etc…

GET /api/domains/5/subnets <- list subnets for a domain

This treats subnets as an actual resource, but allows you to list the
sub-collection easily. Alternatively they should all exist within
/api/domains/5/subnets/, the mixing of paths for the same resource will
only lead to confusion IMHO.

-Justin

··· On 09/16/2013 12:08 PM, Joseph Magen wrote:
  1. Versioning
  • to be discussed further
  1. Hypermedia HATEOS feaures
  • not for v2
  • possibly will be implemented later

More discussion and comments is welcomed.

Regards,

Joseph Magen
Red Hat

----- Original Message -----
From: “Joseph Magen” jmagen@redhat.com
To: “katello-devel” katello-devel@redhat.com
Sent: Monday, August 19, 2013 1:23:36 PM
Subject: Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2. I think this will be helpful for developers of the API as well as clients the consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing fields= or expand=)
  5. Default response for single objects (without explicity passing fields= or expand=)
  6. Customized Responses (fields=, expand=)
  7. Separate API routes for all nested resources
  8. Hypermedia HATEOS feaures
  9. Versioning

Feel free to add more topics or comment on existing one. In most cases, I think it’s best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat

The discussion on conventions is being finalized in this pull-request to
docs:

https://github.com/theforeman/theforeman.org/pull/106

··· On Friday, October 4, 2013 5:15:06 AM UTC-4, Joseph Magen wrote: > > We decided that resources can also be created in the nested root as well. > > Joseph > > > ----- Original Message ----- > From: "Thomas McKay" <thomas...@gmail.com > > To: forem...@googlegroups.com > Cc: katel...@googlegroups.com > Sent: Friday, October 4, 2013 4:57:46 AM > Subject: [foreman-dev] Re: Foreman & Katello API v2 Conventions - etherpad > discussion > > What was decided for POST creation of new objects in v2, nested in > resource > or root level? > > POST /something {something: {name:foo, value:123}} > > or > > POST /something {name:foo, value:123} > > -- > 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 . > For more options, visit https://groups.google.com/groups/opt_out. >

>
>>
>> Re-sending (I sent it the wrong katello-devel address)
>>
>> --------
>> Here is a summary from the etherpad and internal discussion for the of
the Foreman API v2 conventions.
>>
>> We can continue the discussion here by email.
>>
>> 1) Overview of rabl file structure/setup and URL override parameters
>>
>> * Three partials for each object
>> 1) base - minimal fields such as :id, :name and possibly more
depending on object
>> 2) main - 'important' fields (varies depending on object)
>> 3) full - all fields in object
>> * Option to override default fields by passing fields= as URL parameter
>> 1) fields=common-delimited list - Ex.
api/hosts?fields=name,ip,mac,environment
>> 2) fields=full - return all fields
>> 3) fields=base - return base fields
>> * Include time-stamps by default on 'main' and 'full' partials
>> * If there is belong_to field (ex. environment), include _id and _name
by default (ex. environment_id, environment_name)
>> * Option to expand has_many (nested) relationships by passing expand= as
URL parameter
>> * For each expand= relationship, can include (option) in parentheses.
options include:
>> 1) () nothing - 'base' fields by default. Ex.
api/domains?expand=parameters
>> 2) (main) - 'main' fields Ex. api/domains?expand=parameters(main)
>> 3) (full) - 'full' fields Ex. api/domains?expand=parameters(full)
>> 4) (field list) - Ex. api/domains?expand=parameters(name,value)
>> 5) (ids) - same as passing *_ids attribute into fields= Ex.
api/domains?expand=parameters(ids)
>> 6) (names) - same as passing *_names attribute into fields= Ex.
api/domains?expand=parameters(names)
>>
>>
>> 2) JSON Response for Collections
>>
>> Node Name:
>> * default collection root node name is 'results'
>> * option to change default to controller_name (ex. domains,
environments, etc) in rabl_init.rb
>> * option to manually pass root_name as URL parameter (e.x.
/api/domains?root_name=data
>> * option to remove root node by passing root_name=false (e.x.
/api/domains?root_name=false)
>>
>> Response Fields:
>> * show 'main' fields by default for collection
>> * do not show has_many (nested) relationships by default
>> * override default by passing fields=, expand=relationship(option)
>>
>>
>> 3) JSON Response for Individual Object
>>
>> Node Name:
>> * default object root node name is 'object name' (ex. domain,
environment, etc)
>> * option to manually pass object_name as URL parameter (e.x.
/api/domains/11?object_name=record)
>> * option to remove object root node by passing object_name=false (e.x.
/api/domains/11?object_name=false)
>>
>> Response Fields:
>> * show 'full' fields by default for individual object
>> * do not show has_many (nested) relationships by default
>> * override default by passing fields=, expand=relationship(option)
>>
>> 4) Meta Data for Pagination Collections
>>
>> * metadata added by default on collections
>> * attribute names of metadata still to be determined: total, subtotal,
limit, offset, page, per_page, search, sort, etc
>>
>>
>> 5) Nested API routes (ex. GET /api/domains/5/subnets)
>> * Nested routes for :index, :show, and :create operations (only when
needed)
>> * Use root-level resources for :update and :destroy (where there's an id)
>
>
> so this means to 'show' a subnet I would use GET /api/domains/5/subnets/3
>
> but to delete I would use: DELETE /api/subnets/3 ?
>
>
> To me this is quite confusing. Using different urls for delete/update
vs show/create makes it much more difficult/annoying to implement a client
to the apis.
>
> I would prefer to see:
>
> GET /api/subnets <- list all visible subnets
> GET /api/subnets/3
> POST /api/subnets
> PUT /api/subnets/3
> DELETE /api/subnets/3
> etc…
>
> GET /api/domains/5/subnets <- list subnets for a domain
>
> This treats subnets as an actual resource, but allows you to list the
sub-collection easily. Alternatively they should all exist within
/api/domains/5/subnets/, the mixing of paths for the same resource will
only lead to confusion IMHO.
>
> -Justin
>

+1 to everything Justin said.
-d

>
>
>>
>> 6) Versioning
>> * to be discussed further
>>
>>
>> 7) Hypermedia HATEOS feaures
>> * not for v2
>> * possibly will be implemented later
>>
>>
>> More discussion and comments is welcomed.
>>
>> Regards,
>>
>> Joseph Magen
>> Red Hat
>>
>>
>> From: "Joseph Magen" <jmagen@redhat.com>
>> To: "katello-devel" <katello-devel@redhat.com>
>> Sent: Monday, August 19, 2013 1:23:36 PM
>> Subject: Foreman & Katello API v2 Conventions - etherpad discussion
>>
>> Hi all,
>>
>> I started an etherpad so we can discuss some conventions for API v2. I
think this will be helpful for developers of the API as well as clients the
consume the Foreman & Katello APIs.
>>
>> http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2
>>
>> The initial topics are as follows:
>>
>> 1) JSON Response for Collections
>> 2) JSON Response for Single Object
>> 3) Meta Data for Pagination Collections
>> 4) Default response for collections (without explicity passing fields=
or expand=)
>> 5) Default response for single objects (without explicity passing
fields= or expand=)
>> 6) Customized Responses (fields=, expand=)
>> 7) Separate API routes for all nested resources
>> 8) Hypermedia HATEOS feaures
>> 9) Versioning
>>
>> Feel free to add more topics or comment on existing one. In most cases,
I think it's best to write comments, +1, -1 on the etherpad.
>>
>> Regards,
>>
>> Joseph Magen
>> Red Hat
>>
>
> –
> 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.

··· On Sep 16, 2013 7:05 PM, "Justin Sherrill" wrote: > On 09/16/2013 12:08 PM, Joseph Magen wrote: >> ----- Original Message ----- > For more options, visit https://groups.google.com/groups/opt_out.

Updated based on Justin and Dimitri's comments

  1. Nested API routes (ex. GET /api/domains/5/subnets)
  • Nested routes for all actions - :index, :show, :create, :update, :delete

examples:

GET /api/domains/5/subnets <- list all visible subnets related to domain #5
GET /api/domains/5/subnets/3 <- get subnet #3 (and ensure that it is related to domain #5)
POST /api/domains/5/subnets <- create new subnet and associated it with domain #5
PUT /api/domains/5/subnets/3 <- update subnet #3 (and ensure that it is related to domain #5)
DELETE /api/domains/5/subnets/3 <- delete subnet #3 (and ensure that it is related to domain #5)

··· ----- Original Message ----- From: "Dmitri Dolguikh" To: foreman-dev@googlegroups.com Sent: Monday, September 16, 2013 8:23:33 PM Subject: Re: [foreman-dev] Re: [katello-devel] Foreman & Katello API v2 Conventions - etherpad discussion

On Sep 16, 2013 7:05 PM, “Justin Sherrill” jsherril@redhat.com wrote:

On 09/16/2013 12:08 PM, Joseph Magen wrote:

Re-sending (I sent it the wrong katello-devel address)


Here is a summary from the etherpad and internal discussion for the of
the Foreman API v2 conventions.

We can continue the discussion here by email.

  1. Overview of rabl file structure/setup and URL override parameters
  • Three partials for each object
    1. base - minimal fields such as :id, :name and possibly more
      depending on object
  1. main - ‘important’ fields (varies depending on object)
  2. full - all fields in object
  • Option to override default fields by passing fields= as URL parameter
    1. fields=common-delimited list - Ex.
      api/hosts?fields=name,ip,mac,environment
  1. fields=full - return all fields
  2. fields=base - return base fields
  • Include time-stamps by default on ‘main’ and ‘full’ partials
  • If there is belong_to field (ex. environment), include _id and _name
    by default (ex. environment_id, environment_name)
  • Option to expand has_many (nested) relationships by passing expand= as
    URL parameter
  • For each expand= relationship, can include (option) in parentheses.
    options include:
  1. () nothing - ‘base’ fields by default. Ex.
    api/domains?expand=parameters
  1. (main) - ‘main’ fields Ex. api/domains?expand=parameters(main)
  2. (full) - ‘full’ fields Ex. api/domains?expand=parameters(full)
  3. (field list) - Ex. api/domains?expand=parameters(name,value)
  4. (ids) - same as passing *_ids attribute into fields= Ex.
    api/domains?expand=parameters(ids)
  1. (names) - same as passing *_names attribute into fields= Ex.
    api/domains?expand=parameters(names)
  1. JSON Response for Collections

Node Name:

  • default collection root node name is ‘results’
  • option to change default to controller_name (ex. domains,
    environments, etc) in rabl_init.rb
  • option to manually pass root_name as URL parameter (e.x.
    /api/domains?root_name=data
  • option to remove root node by passing root_name=false (e.x.
    /api/domains?root_name=false)

Response Fields:

  • show ‘main’ fields by default for collection
  • do not show has_many (nested) relationships by default
  • override default by passing fields=, expand=relationship(option)
  1. JSON Response for Individual Object

Node Name:

  • default object root node name is ‘object name’ (ex. domain,
    environment, etc)
  • option to manually pass object_name as URL parameter (e.x.
    /api/domains/11?object_name=record)
  • option to remove object root node by passing object_name=false (e.x.
    /api/domains/11?object_name=false)

Response Fields:

  • show ‘full’ fields by default for individual object

  • do not show has_many (nested) relationships by default

  • override default by passing fields=, expand=relationship(option)

    1. Meta Data for Pagination Collections
  • metadata added by default on collections

  • attribute names of metadata still to be determined: total, subtotal,
    limit, offset, page, per_page, search, sort, etc

  1. Nested API routes (ex. GET /api/domains/5/subnets)
  • Nested routes for :index, :show, and :create operations (only when
    needed)
  • Use root-level resources for :update and :destroy (where there’s an id)

so this means to ‘show’ a subnet I would use GET /api/domains/5/subnets/3

but to delete I would use: DELETE /api/subnets/3 ?

To me this is quite confusing. Using different urls for delete/update
vs show/create makes it much more difficult/annoying to implement a client
to the apis.

I would prefer to see:

GET /api/subnets <- list all visible subnets
GET /api/subnets/3
POST /api/subnets
PUT /api/subnets/3
DELETE /api/subnets/3
etc…

GET /api/domains/5/subnets <- list subnets for a domain

This treats subnets as an actual resource, but allows you to list the
sub-collection easily. Alternatively they should all exist within
/api/domains/5/subnets/, the mixing of paths for the same resource will
only lead to confusion IMHO.

-Justin

+1 to everything Justin said.
-d

  1. Versioning
  • to be discussed further
  1. Hypermedia HATEOS feaures
  • not for v2
  • possibly will be implemented later

More discussion and comments is welcomed.

Regards,

Joseph Magen
Red Hat

----- Original Message -----
From: “Joseph Magen” jmagen@redhat.com
To: “katello-devel” katello-devel@redhat.com
Sent: Monday, August 19, 2013 1:23:36 PM
Subject: Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2. I
think this will be helpful for developers of the API as well as clients the
consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing fields=
    or expand=)
  1. Default response for single objects (without explicity passing
    fields= or expand=)
  1. Customized Responses (fields=, expand=)
  2. Separate API routes for all nested resources
  3. Hypermedia HATEOS feaures
  4. Versioning

Feel free to add more topics or comment on existing one. In most cases,
I think it’s best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat


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.


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.

>
> >
> >>
> >> Re-sending (I sent it the wrong katello-devel address)
> >>
> >> --------
> >> Here is a summary from the etherpad and internal discussion for the
> of the Foreman API v2 conventions.
> >>
> >> We can continue the discussion here by email.
> >>
> >> 1) Overview of rabl file structure/setup and URL override parameters
> >>
> >> * Three partials for each object
> >> 1) base - minimal fields such as :id, :name and possibly more
> depending on object
> >> 2) main - 'important' fields (varies depending on object)
> >> 3) full - all fields in object
> >> * Option to override default fields by passing fields= as URL parameter
> >> 1) fields=common-delimited list - Ex.
> api/hosts?fields=name,ip,mac,environment
> >> 2) fields=full - return all fields
> >> 3) fields=base - return base fields
> >> * Include time-stamps by default on 'main' and 'full' partials
> >> * If there is belong_to field (ex. environment), include _id and
> _name by default (ex. environment_id, environment_name)
> >> * Option to expand has_many (nested) relationships by passing
> expand= as URL parameter
> >> * For each expand= relationship, can include (option) in
> parentheses. options include:
> >> 1) () nothing - 'base' fields by default. Ex.
> api/domains?expand=parameters
> >> 2) (main) - 'main' fields Ex. api/domains?expand=parameters(main)
> >> 3) (full) - 'full' fields Ex. api/domains?expand=parameters(full)
> >> 4) (field list) - Ex. api/domains?expand=parameters(name,value)
> >> 5) (ids) - same as passing *_ids attribute into fields= Ex.
> api/domains?expand=parameters(ids)
> >> 6) (names) - same as passing *_names attribute into fields= Ex.
> api/domains?expand=parameters(names)
> >>
> >>
> >> 2) JSON Response for Collections
> >>
> >> Node Name:
> >> * default collection root node name is 'results'
> >> * option to change default to controller_name (ex. domains,
> environments, etc) in rabl_init.rb
> >> * option to manually pass root_name as URL parameter (e.x.
> /api/domains?root_name=data
> >> * option to remove root node by passing root_name=false (e.x.
> /api/domains?root_name=false)
> >>
> >> Response Fields:
> >> * show 'main' fields by default for collection
> >> * do not show has_many (nested) relationships by default
> >> * override default by passing fields=, expand=relationship(option)
> >>
> >>
> >> 3) JSON Response for Individual Object
> >>
> >> Node Name:
> >> * default object root node name is 'object name' (ex. domain,
> environment, etc)
> >> * option to manually pass object_name as URL parameter (e.x.
> /api/domains/11?object_name=record)
> >> * option to remove object root node by passing object_name=false
> (e.x. /api/domains/11?object_name=false)
> >>
> >> Response Fields:
> >> * show 'full' fields by default for individual object
> >> * do not show has_many (nested) relationships by default
> >> * override default by passing fields=, expand=relationship(option)
> >>
> >> 4) Meta Data for Pagination Collections
> >>
> >> * metadata added by default on collections
> >> * attribute names of metadata still to be determined: total,
> subtotal, limit, offset, page, per_page, search, sort, etc
> >>
> >>
> >> 5) Nested API routes (ex. GET /api/domains/5/subnets)
> >> * Nested routes for :index, :show, and :create operations (only when
> needed)
> >> * Use root-level resources for :update and :destroy (where there's
> an id)
> >
> >
> > so this means to 'show' a subnet I would use GET /api/domains/5/subnets/3
> >
> > but to delete I would use: DELETE /api/subnets/3 ?
> >
> >
> > To me this is quite confusing. Using different urls for
> delete/update vs show/create makes it much more difficult/annoying to
> implement a client to the apis.
> >
> > I would prefer to see:
> >
> > GET /api/subnets <- list all visible subnets
> > GET /api/subnets/3
> > POST /api/subnets
> > PUT /api/subnets/3
> > DELETE /api/subnets/3
> > etc…
> >
> > GET /api/domains/5/subnets <- list subnets for a domain
> >
> > This treats subnets as an actual resource, but allows you to list the
> sub-collection easily. Alternatively they should all exist within
> /api/domains/5/subnets/, the mixing of paths for the same resource will
> only lead to confusion IMHO.
> >
> > -Justin
> >
>
> +1 to everything Justin said.
> -d

+1 I prefer the same

··· On 09/16/2013 07:23 PM, Dmitri Dolguikh wrote: > On Sep 16, 2013 7:05 PM, "Justin Sherrill" > wrote: > > On 09/16/2013 12:08 PM, Joseph Magen wrote:
  1. Versioning
  • to be discussed further
  1. Hypermedia HATEOS feaures
  • not for v2
  • possibly will be implemented later

More discussion and comments is welcomed.

Regards,

Joseph Magen
Red Hat

----- Original Message -----
From: “Joseph Magen” <jmagen@redhat.com mailto:jmagen@redhat.com>
To: “katello-devel” <katello-devel@redhat.com
mailto:katello-devel@redhat.com>

Sent: Monday, August 19, 2013 1:23:36 PM
Subject: Foreman & Katello API v2 Conventions - etherpad discussion

Hi all,

I started an etherpad so we can discuss some conventions for API v2.
I think this will be helpful for developers of the API as well as
clients the consume the Foreman & Katello APIs.

http://etherpad-domcleal.rhcloud.com/p/foreman_api_v2

The initial topics are as follows:

  1. JSON Response for Collections
  2. JSON Response for Single Object
  3. Meta Data for Pagination Collections
  4. Default response for collections (without explicity passing
    fields= or expand=)
  1. Default response for single objects (without explicity passing
    fields= or expand=)
  1. Customized Responses (fields=, expand=)
  2. Separate API routes for all nested resources
  3. Hypermedia HATEOS feaures
  4. Versioning

Feel free to add more topics or comment on existing one. In most
cases, I think it’s best to write comments, +1, -1 on the etherpad.

Regards,

Joseph Magen
Red Hat


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
mailto:foreman-dev%2Bunsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.


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.