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

[Dmitri Dolguikh]

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