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

[Dmitri Dolguikh]

On 05/03/13 03:37 PM, Tom McKay wrote:
>
> ----- 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)?
That's the idea.
-d