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

[Tom McKay]

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

> 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