[katello-devel] [foreman-dev] Re: Foreman & Katello API v2 Conventions - etherpad discussion

Tue Sep 17 06:41:41 UTC 2013

Updated based on Justin and Dimitri's comments

5) 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" <witlessbird at gmail.com>
To: foreman-dev at 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 at 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
>>    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
>>
>>
>> ----- Original Message -----
>> From: "Joseph Magen" <jmagen at redhat.com>
>> To: "katello-devel" <katello-devel at 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 at 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 at googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.