[katello-devel] API v2 - proposed changes in routes

[Dmitri Dolguikh]

Thanks for sharing the ongoing work - this is awesome. Please see 
comments below.

On 05/03/13 12:57 PM, Tomas Strachota wrote:
> Hi team,
> Martin and me are working on API v2. We went through the pain points 
> that were discovered and described during documentation process of v1 
> [1].
>
> In terms of routing the changes we propose are summarized in [2].
> I divided them into 4 groups:
>  1) routes created by mistake in routes.rb or unused routes
>  2) routes nested too deep

It appears sync_plans resource uses a non-unique resource id which has 
to be used in the context of its parent resource (see 
https://github.com/Katello/katello/blob/master/src/app/controllers/api/sync_plans_controller.rb#L109). 
I don't know the reasons behind sync_plan not being globally unique.

The rest of the changes look ok.

>
>  3) other duplicate or not much resty routes
>  4) RPC-like calls I guess we can't do anything with


   /api/providers/:id/refresh_products(.:format) Ought to be a dedicated 
resource (possibly and async operation). Probably should return status 
of each product refresh (the operation can fail)

   /api/content_views/:id/refresh and /api/content_views/:id/promote - 
both are async tasks, I think it would be better to introduce resources 
like:

content_views/tasks/promotion
content_views/tasks/refresh

or

content_views/:id/tasks/promotion
content_views/:id/tasks/refresh

and then use returned task id to track the status via

tasks/:id

same goes for POST /api/changesets/:id/apply(.:format)


> The routes in the etherpad are in "rake routes" format with comments 
> under each of them.
>
> There are also planned changes in output json format and accepted 
> parameter. We will describe them in separate email.
>
> In a discussion on irc Jeff suggested new feature - possibility to 
> identify resources by it's names. I think it's something we can extend 
> the clean api v2 with later. For sake of simplicity and speed of 
> development I'd rather stay only with cleanup and making the api 
> consistent. We can do names as identifiers later as a separate task if 
> we find it useful.

We had this discussion awhile ago. I think we should support searching 
by any attribute (or combination). Using two resource ID's is probably 
not worth the trouble, and the bigger issue is using intrinsically 
non-unique names/labels for resource identification, as it drags in 
issues with renames (should we return 301?), delete and create (should 
we prevent from creating new resources with the name of the deleted one? 
What about the users who are unaware of the delete and now think that 
the resource has simply been updated?), etc, etc.

Cheers,
-d

>
> Opinions are welcome
> Tomas
>
> [1] https://fedorahosted.org/katello/wiki/APIDocumentationEfforts
> [2] https://pad-katello.rhcloud.com/p/API_v2_routes
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/katello-devel/attachments/20130305/c9ca110b/attachment.htm>