> 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:
- Versioning
- 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:
- JSON Response for Collections
- JSON Response for Single Object
- Meta Data for Pagination Collections
- Default response for collections (without explicity passing fields= or expand=)
- Default response for single objects (without explicity passing fields= or expand=)
- Customized Responses (fields=, expand=)
- Separate API routes for all nested resources
- Hypermedia HATEOS feaures
- 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