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

[Dmitri Dolguikh]

On 05/03/13 03:46 PM, Justin Sherrill wrote:
> On 03/05/2013 10:43 AM, Tom McKay wrote:
>>
>> ----- Original Message -----
>>> From: "Justin Sherrill"<jsherril at redhat.com>
>>> To: katello-devel at redhat.com
>>> Sent: Tuesday, March 5, 2013 10:39:44 AM
>>> Subject: Re: [katello-devel] API v2 - proposed changes in routes
>>>
>>>
>>> On 03/05/2013 10:28 AM, Dmitri Dolguikh wrote:
>>>
>>>
>>> On 05/03/13 02:52 PM, Eric D Helms wrote:
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>>
>>> 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.
>>> API doesn't have a concept of the 'current' organization, which is
>>> another hint at the fact that API is used differently from UI. Using
>>> organizations and environments as an example, a typical flow would
>>> be:
>>>
>>> GET organizations/:id/environments
>>> PUT environments/:id
>>>
>>> The presence of the organization bit in the url would imply to me
>>> that the environment id is unique within organization only (which
>>> has its own consequences). As this is not the case here,
>>> organization information isn't merely noise, it's misleading.
>>>
>>> I think not having the org_id in the url makes our api much more
>>> confusing today. For example,
>>>
>>> GET environments/ requires organization_id as a parameter, as does
>>> POST environments/
>>>
>> I think GET /environments/ would return _all_ environments for _all_ 
>> orgs. Adding ?org_id=1 would limit (as would adding ?org_label=ACME).
>
> And that would make sorta sense logically (although its not what we do).

It is the logic we follow in API. However collection index and create 
operations are not available from the top-level "environments" resource, 
only through the "organization" parent.

>
>
> Do we really want to list all environments across all orgs? 

I doubt it.


> Do we want to list every/any arbitrary resource across all orgs?

I doubt it.

>
> Especially considering names of things can be the same across orgs, 
> could it be confusing?  We are very explicit in the UI and cli that 
> the user is working within a single org, do we want to break that 
> philosophy in the api?

I pointed this out in reply to Eric: API is used differently from UI; 
adding organization information to the resource url carries semantic 
load (at least to people familiar with REST), and therefore should only 
be used when said relation needs to be expressed.

-d