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

[Dmitri Dolguikh]

On 05/03/13 03:39 PM, Justin Sherrill wrote:
> 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 <mailto: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/
>
> 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 think we are now in the subjective territory, and the conversations 
about what would or would not be confusing to users are speculative. In 
my reasoning I relied on how resources and their collections are 
commonly expressed. This approach shouldn't come as a surprise (perhaps 
worth documenting this though?).

I somewhat agree re: resource ids: Ideally, any resource id should be 
globally unique for this resource if it was automatically generated. I 
don't think this is always the case in Katello (the side-effect of 
having "user-friendly" ids), hence the disclaimer. I disagree whether 
users should be aware the scope of resource ids - they should be, 
especially if it's atypical.

-d



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