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

[Bryan Kearney]

On 03/05/2013 09:52 AM, 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.
>
> 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.


I think the API should have all actions available to it, but I dont know 
if it should mimic the UI. If user create is in /admin today i dont 
think the api should be:

/admin/users

it should just be

/users

-- bk