[katello-devel] API V2 format changes

[Jeff Weiss]

Martin Bacovsky <mbacovsk at redhat.com> writes:

> 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
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel

Sounds great!  I have some opinions on a couple of items:

* Support messages in 2XX responses?  No, unless there's something to be
  conveyed, beyond "the operation succeeded".  The success should be
  evident by the response code right?  That's a lot easier to check than
  an english string.

* Return entities in the body?  I'd at least want the ability to do
  this, it makes it easier to sync the client's representation of the
  entity if you get the whole thing back.  I'd say make it an option in
  the request, but if it hurts performance (and it probably will), leave
  it off by default.

* Pagination - If the caller can freely set the items per page and page
  number, just let him specify the range of items he wants:
  /api/organizations/<org>/environments/?range=40-60 (last is exclusive
  here).  No need to return any pagination or range information in
  the response, AFAICT, since the caller knows it already.  eg, he
  requests ?range=40-60 and there are only 47 items, he knows he's
  getting items 40-47 by counting the items.  I'm not sure what the REST
  way of saying we're past the end of the list?  either empty list or
  404 i guess.

-Jeff





-- 
Jeff Weiss
Principal Quality Assurance Engineer
jweiss at redhat.com
(919)886-6533