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

[Tomas Strachota]

On 03/05/2013 02:29 PM, Eric D Helms wrote:
> On #2, if one of our core operating principles is that nearly everything
> is scoped based on an organization, why would we want to abstract that
> away and not make it explicit as part of resource look-up?  Given that a
> design goal of RESTful APIs is to be predictable, I would think the form
> that includes organization at the trunk of the route is more predictable
> and mimics how resources are structured.
>

The idea was not to get rid of the resource relations. The scope would 
still be there for collections. For example environments would look like:

crate:   POST   /organization/ACME/
list:    GET    /organization/ACME/environments/
show:    POST   /environments/1/
update:  PUT    /environments/1/
destroy: DELETE /environments/1/

I think of it like this:
I want to see what environments I have in org ACME -> I go to 
/organization/ACME/environments/. Now I know ids of all the environments 
I'm interested in. If I want to change it, I know it's environment so I 
go to /environments/1/. I don't have to keep in mind what org it's in.
When whole api behaves the same I find it predictable.

Basically everything in Katello is scoped under orgs. I'm afraid that if 
we wanted to be consistent and keep the full paths, we would get really 
long routes like
DELETE /organization/ACME/changesets/:id/packages/:id/

> On changes to JSON format, I would like to make the request that there
> be thought put into API "paging".  I am starting to work on using the
> API for some UI components and adding our Elasticsearch infrastructure
> to these API calls.  This typically involves requesting a chunk of
> resources (say 25 for example) and then requesting the next 25 as the
> user demands them.  As well, being able to look at the returned data to
> know the total number of records even though I am only getting say 26-50
> with that particular call.
>

+1 I like paging.

>
> - Eric
>
>
> On Tue, Mar 5, 2013 at 8:21 AM, Jeff Weiss <jweiss at redhat.com
> <mailto:jweiss at redhat.com>> wrote:
>
>     Tomas Strachota <tstrachota at redhat.com
>     <mailto:tstrachota at redhat.com>> writes:
>
>      > 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
>      >   3) other duplicate or not much resty routes
>      >   4) RPC-like calls I guess we can't do anything with
>      > 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.
>      >
>      > 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 <mailto:katello-devel at redhat.com>
>      > https://www.redhat.com/mailman/listinfo/katello-devel
>
>     Looks good to me.
>
>     Fixing #2 will be helpful to me as well, it will require fewer queries
>     to get id's.
>
>     --
>     Jeff Weiss
>     Principal Quality Assurance Engineer
>     jweiss at redhat.com <mailto:jweiss at redhat.com>
>     (919)886-6533 <tel:%28919%29886-6533>
>
>     _______________________________________________
>     katello-devel mailing list
>     katello-devel at redhat.com <mailto:katello-devel at redhat.com>
>     https://www.redhat.com/mailman/listinfo/katello-devel
>
>