[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:34:45 AM
> Subject: Re: [katello-devel] API v2 - proposed changes in routes
> 
> 
> >>> 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
> 
> Sure. The difference between the last two (and the last call should
> really be GET /environments/1 unless environment id is non-unique
> globally) is that:
> 
>   - GET /organizations/:id/environments?id=1 (or any other attribute)
> either returns a list of matching resources, or an empty list
>   - GET /organizations/:id/environments/1 either returns the resource
> (singular), or a 404
> 
> In other words, the difference in semantics between "get" (the
> resource
> is expected to exist) and "find" (may or may not exist) calls.
> 
> -d
> 
> 

So all the param-based calls would return list (or empty list), while explicit use of /$id would return single item (or 404)?