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

[Dmitri Dolguikh]

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