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

Tue Mar 5 14:52:13 UTC 2013

On Tue, Mar 5, 2013 at 9:11 AM, Tomas Strachota <tstrachota at redhat.com>wrote:

> 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.
>
> Given that the API is another user interface, I feel that it's important
for all our interfaces to mimic one another in structure as well as keep
certain details in the forefront of users minds.  In the UI, most entities
are scoped based on Organization and this is expressed throughout the
design goals.  This should, in my opinion, spill over into the API so that
resources are predictable and mimic other workflows the user will be
accustomed to.  Using our API, I should have to actively deal with the fact
that System A is a part of Org X to help me understand the implications and
because this is a built in hierarchy that we've expressed as a guiding
principle of our design.

I can understand your argument for predictability, but if I start querying
the collection via /organization/ACME_Corporation/environments/, based on
the principles of REST, I would expect that I can just add an ID to the end
of that URL and acquire the specific resource.

Eric

> 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<https://fedorahosted.org/katello/wiki/APIDocumentationEfforts>
>>      > [2] https://pad-katello.rhcloud.**com/p/API_v2_routes<https://pad-katello.rhcloud.com/p/API_v2_routes>
>>      >
>>      > ______________________________**_________________
>>      > katello-devel mailing list
>>      > katello-devel at redhat.com <mailto:katello-devel at redhat.**com<katello-devel at redhat.com>
>> >
>>
>>      > https://www.redhat.com/**mailman/listinfo/katello-devel<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<katello-devel at redhat.com>
>> >
>>     https://www.redhat.com/**mailman/listinfo/katello-devel<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/f5c1b2cc/attachment.htm>