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

[Dmitri Dolguikh]

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 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/katello-devel/attachments/20130305/ae07c878/attachment.htm>