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

Tue Mar 5 17:39:14 UTC 2013

On 03/05/2013 06:34 PM, Tomas Strachota wrote:
> On 03/05/2013 05:25 PM, Dmitri Dolguikh wrote:
>> On 05/03/13 03:46 PM, Justin Sherrill wrote:
>>> On 03/05/2013 10:43 AM, Tom McKay wrote:
>>>>
>>>> ----- Original Message -----
>>>>> From: "Justin Sherrill"<jsherril at redhat.com>
>>>>> To: katello-devel at redhat.com
>>>>> Sent: Tuesday, March 5, 2013 10:39:44 AM
>>>>> Subject: Re: [katello-devel] API v2 - proposed changes in routes
>>>>>
>>>>>
>>>>> 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>  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/
>>>>>
>>>> I think GET /environments/ would return _all_ environments for _all_
>>>> orgs. Adding ?org_id=1 would limit (as would adding ?org_label=ACME).
>>>
>>> And that would make sorta sense logically (although its not what we do).
>>
>> It is the logic we follow in API. However collection index and create
>> operations are not available from the top-level "environments" resource,
>> only through the "organization" parent.
>>
>>>
>>>
>>> Do we really want to list all environments across all orgs?
>>
>> I doubt it.
>>
>>
>>> Do we want to list every/any arbitrary resource across all orgs?
>>
>> I doubt it.
>>
>>>
>>> Especially considering names of things can be the same across orgs,
>>> could it be confusing?  We are very explicit in the UI and cli that
>>> the user is working within a single org, do we want to break that
>>> philosophy in the api?
>>
>
> I don't see it as breaking the philosophy. We actually want to emphasize
> that we're working within an org by removing all routes that list the
> resources globally (eg. get /systems, get /envs).
>
> I understand your concerns about the intuitiveness for users.
> In my opinion, removing redundant unique ids would make potential api
> bindings simpler (eg. our cli python bindings) and more intuitive from
> coder's point of view.
> Do you think it would help users if we added links to resources into our
> json responses? Something like get on /organizations/:id/environments
> would return
> [{
>    environment: {
>      ...
>    },
>    links: [{
>      name: show,
>      href: /environments/:id/
>    }]
> }]
>

Sorry, I meant
      ...
      href: /environments/1/
      ...
No intention to do any kind of templating in the urls.


> T.
>
>> I pointed this out in reply to Eric: API is used differently from UI;
>> adding organization information to the resource url carries semantic
>> load (at least to people familiar with REST), and therefore should only
>> be used when said relation needs to be expressed.
>>
>> -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