[katello-devel] API V2 format changes

[Martin Bacovsky]

We (Tomas and Martin) are working on API redesign and cleanup. The 
motivation for this is that the practices are not consistent in current 
API which makes UX not pleasant and is causing difficulties while 
creating CLI. In the future it could be possible to autogenerate python 
bindings for Katello  and/or parts of the CLI.

Current state
     * nesting of elements is not consistent
     * when use of as_json the representation of entities is distributed 
over the code
     * some results render as text instead of JSON

Our goals:
     * make the transition as simple as possible
     * use RABL for JSON output definition
     * make responses consistent
     * unify error handling
     * make it easy to change the output behaviour from one place

There are some decision that needs to be done. We are looking for 
opinions on following things:

     Support messages in 2XX responses? e.g. 'message: "Environment was 
successfully deleted"'

     Pagination handeling
     * support in every GET that returns collection or just where it 
make sense?
     * suggested format 
/api/organizations/<org>/environments/?page=2&items_per_page=20
     * Should result contain item count, offset, items per page?

     POST
     * return 201 or 200?
     * return URI or entitiy in body?

     PUT
     * return entity or empty body?

JSON conventions for V2 as we would prefer them to be, but is subject to 
changes according to comments on questions s above

     GET
     * returns either entity or list of entities
     * pagination supported where it makes sense, no extra information 
in paginated response, add methods entities_count or similar
     * all entities have root

     POST
     * 201
     * return entity in body, URI in Location

     PUT
     * 200
     * entity in body

     DELETE
     * 200
     * empty body

     No messages in 2XX responses. (status of the action is told by the 
code, passing it to the user should be responsibility of client app)


Work shown in the pull request 
(https://github.com/Katello/katello/pull/1714) should demonstrate the 
desired state of things after our mission is completed. We choosed 
environments as a suitable sample controller:

     V1 refactoring to minimize changes in controllers in V2 and to 
avoid support of two sets of controllers as much as possible
     * isolated output handling to set of methods, taht could be changed 
in the next version without need to touch the controllers
     * keep the V1 behavior unchanged is priority
     * change inheritance of the controllers to allow inherit V2 
controllers from the V1 ones while adding V2 specific behaviour from module

     V2
     * added RABL templates

TODO
     * handeling of errors in V2
     * pagination support

Comments are welcome,
Martin