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

[Justin Sherrill]

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

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

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?

-Justin

>> so the user is left guessing, does this require an org_id or not? I
>> also think the concept of "if the environment id is unique within
>> the org only or not" is moot, as the user does not define the id, so
>> why does he care under what scope is it unique? If the id was set by
>> the user that might be a valid point.
>>
>> -Justin
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> 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.
>> What principle[s] of REST do you refer to here?
>>
>> -d
>>
>>
>> _______________________________________________
>> katello-devel mailing list katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel
>>
>> _______________________________________________
>> katello-devel mailing list
>> katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel