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

[Tom McKay]

----- Original Message -----
> From: "Dmitri Dolguikh" <dmitri at redhat.com>
> To: "Tom McKay" <thomasmckay at redhat.com>
> Cc: katello-devel at redhat.com
> Sent: Tuesday, March 5, 2013 10:14:12 AM
> Subject: Re: [katello-devel] API v2 - proposed changes in routes
> 
> On 05/03/13 03:05 PM, Tom McKay wrote:
> >
> > ----- Original Message -----
> >> From: "Dmitri Dolguikh" <dmitri at redhat.com>
> >> To: katello-devel at redhat.com
> >> Sent: Tuesday, March 5, 2013 9:27:01 AM
> >> Subject: Re: [katello-devel] API v2 - proposed changes in routes
> >>
> >> On 05/03/13 02:11 PM, Tomas Strachota 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.
> >> +1. That's precisely it. Internally, if you don't do a join on the
> >> organization, its id is superfluous - there's no need to drag it
> >> in
> >> the
> >> resource url.
> >>
> >> -d
> > So we won't allow labels in the URLs, or labels would be required
> > to use the deeper nesting?
> >
> > GET /organization/ACME/environments      -> {id: 1, label: DEV}
> > GET /environment/1                       -> {id: 1, label: DEV}
> > GET /organization/ACME/environments/DEV  -> {id: 1, label: DEV}
> >
> > maybe?
> 
> Heh heh. I suppose labels could be used when the scope is constrained
> (by the organization in this case). However, I would very much prefer
> 
> GET /organization/ACME/environments?label=DEV -> {id: 1, label: DEV}
> 
> As it clearly shows that "DEV" is not an id, and consequently is less
> permanent, and the resource may or may not be there.
> 
> -d

Params would be better. All of the following would return same result:

GET /organization/environments?label=DEV
GET /organization/environments?name=DEV
GET /organization/environments?id=1
GET /organization/environments/1