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

Tue Mar 5 17:00:09 UTC 2013

On 03/05/2013 04:39 PM, Justin Sherrill wrote:
> On 03/05/2013 10:28 AM, Dmitri Dolguikh wrote:
>> On 05/03/13 02:52 PM, Eric D Helms wrote:
>>>
>>>
>>>
>>> On Tue, Mar 5, 2013 at 9:11 AM, Tomas Strachota
>>> <tstrachota at redhat.com <mailto:tstrachota at redhat.com>> 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.
>>>
>>> Given that the API is another user interface, I feel that it's
>>> important for all our interfaces to mimic one another in structure as
>>> well as keep certain details in the forefront of users minds.  In the
>>> UI, most entities are scoped based on Organization and this is
>>> expressed throughout the design goals.  This should, in my opinion,
>>> spill over into the API so that resources are predictable and mimic
>>> other workflows the user will be accustomed to.  Using our API, I
>>> should have to actively deal with the fact that System A is a part of
>>> Org X to help me understand the implications and because this is a
>>> built in hierarchy that we've expressed as a guiding principle of our
>>> design.
>>
>> API doesn't have a concept of the 'current' organization, which is
>> another hint at the fact that API is used differently from UI. Using
>> organizations and environments as an example, a typical flow would be:
>>
>> GET organizations/:id/environments
>> PUT environments/:id
>>
>> The presence of the organization bit in the url would imply to me that
>> the environment id is unique within organization only (which has its
>> own consequences). As this is not the case here, organization
>> information isn't merely noise, it's misleading.
>
> I think not having the org_id in the url makes our api much more
> confusing today.  For example,
>
> GET environments/   requires  organization_id as a parameter, as does
> POST environments/
>
> so the user is left guessing, does this require an org_id or not? I also
> think the concept of "if the environment id is unique within the org
> only or not" is moot, as the user does not define the id, so why does he
> care under what scope is it unique?  If the id was set by the user that
> might be a valid point.
>

I'm not sure if it was obvious but I agree with what you say here. We 
also try to solve this problem in the proposal.
The routes I mention in the etherpad document are always tied to a 
method. If there is a note "Move to" it means we want to move only the 
named methods. The rest would stay as it is.

What I find confusing today:

1) Not having ids of parent resources in the url
This is what you mention above.
GET and POST environments/ requires organization_id as a parameter

Solution:
Nest the GETs (for collection) and POSTs. In this case
GET /organizations/:id/environments/ for listing envs in an org
POST /organizations/:id/environments/ for creating new envs

2) Requiring two unique ids in routes
I guess the problem is understood and we all just differ in opinions.

Proposed solution is to get rid of the redundant ids:
GET /environments/:id/ for showing a single env
PUT /environments/:id/ for updates
DELETE /environments/:id/ for destroy

T.

> -Justin
>
>
>>
>>>
>>> I can understand your argument for predictability, but if I start
>>> querying the collection via
>>> /organization/ACME_Corporation/environments/, based on the principles
>>> of REST, I would expect that I can just add an ID to the end of that
>>> URL and acquire the specific resource.
>>
>> What principle[s] of REST do you refer to here?
>>
>> -d
>>
>>
>> _______________________________________________
>> katello-devel mailing list
>> katello-devel at redhat.com
>> https://www.redhat.com/mailman/listinfo/katello-devel
>
>
>
> _______________________________________________
> katello-devel mailing list
> katello-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/katello-devel
>