[katello-devel] API V2 format changes

[Dmitri Dolguikh]

On 07/03/13 04:46 PM, Martin Bacovsky wrote:
> 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"'

I think messages are redundant: the client knows the resource it's 
accessing, the operation, and can figure out the result based on the 
status code.

>
>     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?

Depends. I think it's wrong to introduce offset and items per page in 
the resource (these reflect iterator/cursor state and should be modelled 
accordingly). Including a hyper-link to retrieve the next x items would 
be ok though.

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

I think either 200 or 201 would be ok (201 is more specific though). The 
main difference between these is that 200 contains the resource itself, 
while 201 only the URI and some metadata. In a lot of cases we are 
actually interested in the created entity, so a 200 response makes the 
life a bit easier.

>
>
>     PUT
>     * return entity or empty body?

204 sounds appealing...

>
> 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

According to the spec it's either 200 + entity or 201 + URI. My vote 
goes for 200.

>
>     PUT
>     * 200
>     * entity in body
>
>     DELETE
>     * 200
>     * empty body

Perhaps 204 or 205 would be better? Empty body by definition. I think 
semantically 205 is more appropriate...

>
>     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

YEAY!!!!!!!!!!!!!!!!!!

>
>
> TODO
>     * handeling of errors in V2
>     * pagination support
>
> Comments are welcome,
> Martin

-d