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

[Justin Sherrill]

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

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