Open Stack

Hi all,

I am currently looking at the Ironic API and was pointed towards the 
etherpad here: https://etherpad.openstack.org/api-version-discovery-proposal

With regards to version discovery I wonder why do we not treat the API 
and the Version simply like any other resource and have them completely 
discoverable.  An example of how I originally had this is shown here: 
https://gist.github.com/mtaylor/5663143//. The example here uses the 
same concepts across the whole of the API.  Therefore there is no need 
to add in extra pieces such as response code 300 with some specific 
document.  The API including versions are fully discoverable and treat 
like any other resource.  To save complexity the API defaults to the 
most recent version should a version not be specified in either the MIME 
type or URL.

What are your thoughts?  Is there some use case where this approach will 
not work.

Regards
Martyn

On 22/05/13 19:53, Gabriel Hurley wrote:
> Totally in favor of the /capabilities/<version> suggestion. I've updated the etherpad to reflect that.
>
> FWIW, I had originally misread your concern in the etherpad as the exact opposite and thought it was a non-issue, hence my clearing it out in the cleanup. Sorry about that. Duly fixed now.
>
> All the best,
>
>      - Gabriel
>
>> -----Original Message-----
>> From: John Dickinson [mailto:me at not.mn]
>> Sent: Monday, May 20, 2013 10:18 AM
>> To: OpenStack Development Mailing List
>> Subject: Re: [openstack-dev] [openstack-tc] Proposal for API version
>> discovery
>>
>> As was mentioned on the etherpad (but since deleted), a
>> /version/capabilities path for discoverability will not work for Swift. Using
>> that pattern, "capabilities" could be a valid account in all existing clusters (eg
>> http://swift/v1/capabilities/). The alternative proposed was for /version-
>> capabilities. I'm also ok with a /capabilities/version pattern.
>>
>> --John
>>
>>
>>
>>
>> On May 14, 2013, at 12:31 PM, Gabriel Hurley <Gabriel.Hurley at nebula.com>
>> wrote:
>>
>>> It seems like there's some reasonable support for going in the direction of
>> HATEOS-esque links for defining capabilities... I suppose it'd be nice to see
>> one of the more extreme examples taken to its logical conclusion. Could
>> someone more familiar with the breadth of Nova's extensions write out
>> what it would look like if you actually provided links for every action
>> reasonably available on a server?
>>> -          Gabriel
>>>
>>> From: Dolph Mathews [mailto:dolph.mathews at gmail.com]
>>> Sent: Monday, May 13, 2013 9:26 AM
>>> To: OpenStack Development Mailing List
>>> Subject: Re: [openstack-dev] [openstack-tc] Proposal for API version
>>> discovery
>>>
>>>
>>> On Thu, May 9, 2013 at 8:40 AM, Mark Washenberger
>> <mark.washenberger at markwash.net> wrote:
>>> I'm not sure that is really 100% of the problem here, but we are definitely
>> doing links in an inefficient way these days, due to an early misconception
>> some of us on the Nova team had about *how* to do hyperlinks in json.
>>> Json schema [1] provides ways to indicate, _in the schema of an
>>> object_, how it is linked to other objects. For example, if I had an
>>> object
>>>
>>> GET /widgets/foo
>>> {
>>>    'name': 'foo',
>>>    'self': '/widgets/foo',
>>>    'bar': '/widgets/foobar',
>>> }
>>>
>>> I might use a schema to communicate that 'self' is a self link, and
>>> that 'bar' is a related resource by publishing a schema
>>>
>>> GET /schemas/object
>>> {
>>>     'type': 'object',
>>>     'properties': {
>>>        'name': {'type': 'string'},
>>>        'self': {'type': 'string'},
>>>        'bar': {'type': 'string'},
>>>     },
>>>     'links': [
>>>        {'rel': 'self', 'href': '{self}'},
>>>        {'rel': 'related', 'href': '{bar}'}
>>>     ]
>>> }
>>>
>>> What this schema says is that name, self, and bar are string types, that you
>> can construct a self link using the value of the "self" property, and that you
>> can construct a related link using the value of the "bar" property.
>>> For some reason I cannot remember, we neglected to realize that link
>> descriptor objects [2] were only intended for json schema objects, not the
>> regular objects described by the schemas. In the process, we made
>> hyperlinks in our apis really inefficient by loading them up with unnecessary
>> 'rels' and 'hrefs'. We also made finding relevant links difficult by requiring
>> clients to iterate through an array rather than just explicitly looking up the
>> relevant properties.
>>> Glance v2 api fixes this problem. But we also tried to go all-in on
>>> being schema driven. This combined approach is fine for Glance, but
>>> I'm not sure that the "schema-driven" part is necessarily that useful
>>> for others. In any case, we needn't have such bloated json hyperlinks
>>> for future openstack apis. For example, if you want to have actions
>>> listed for a server, you could just do
>>>
>>> {
>>>    "id": "abcd",
>>>    ...
>>>    "actions": {
>>>      "stop": "/servers/abcd/stop",
>>>      "snapshot": "/servers/abcd/snapshot"
>>>    }
>>> }
>>>
>>>
>>> +1; identity api v3 addresses this as well, but uses a "links" container to
>> avoid namespace pollution.
>>>    {
>>>      "entity": {
>>>        "id": string,
>>>        "name": string
>>>        "links": {
>>>          "self": url,
>>>          "related_collection": url
>>>        }
>>>      }
>>>    }
>>>
>>> https://github.com/openstack/identity-api/blob/master/openstack-identi
>>> ty-api/src/markdown/identity-api-v3.md#create-an-entity
>>>
>>>
>>> which is a bit more compressed.
>>>
>>> [1] - http://tools.ietf.org/html/draft-zyp-json-schema-03
>>> [2] - http://tools.ietf.org/html/draft-zyp-json-schema-03#section-6.1
>>>
>>>
>>> On Wed, May 8, 2013 at 10:33 PM, Mark McLoughlin
>> <markmc at redhat.com> wrote:
>>> On Wed, 2013-05-08 at 18:59 +0000, Gabriel Hurley wrote:
>>>>> -----Original Message-----
>>>>> From: Vishvananda Ishaya [mailto:vishvananda at gmail.com]
>>>>> Sent: Tuesday, May 07, 2013 3:44 PM
>>>>> It is relatively easy to include the info at servers/<uuid> however:
>>>>> {
>>>>>   "features": ["OS-EXT-SRV-ATTR", "os-start-stop"],
>>>>>   "server": {
>>>>>     "OS-EXT-SRV-ATTR:host": "1169a68456af48238da47b1d5957a714",
>>>>>     "OS-EXT-SRV-ATTR:hypervisor_hostname": "fake-mini",
>>>>>     "OS-EXT-SRV-ATTR:instance_name": "instance-00000001",
>>>>>     "links": [
>>>>>       {"rel": "self",
>>>>>
>>>>> "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
>>>>> 008cfa10b980"},
>>>>>       {"rel": "start",
>>>>>
>>>>> "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
>>>>> 008cfa10b980/start"
>>>>>        "feature": "os-start-stop"},
>>>>>       {"rel": "stop",
>>>>>
>>>>> "href":"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
>>>>> 008cfa10b980/stop"
>>>>>        "feature": "os-start-stop"}.
>>>>>     ]
>>>>>    }
>>>>> }
>>>> Tht perfectly illustrates my biggest concern with doing this on a
>>>> per-resource basis.
>>> Per-resource does allow you to expose whether a user has permission to
>>> perform an action, though.
>>>
>>>>   The list of "links" gets unconscionably enormous. If I do a "list"
>>>> call and retrieve 100 instances each with 100 links because you have
>>>> 20 extensions the whole thing becomes a mess. I think it's much more
>>>> sane (though less explicit) to understand what's provided by the
>>>> service and extrapolate that to the individual resources therein.
>>> Yeah, lots of links can be messy. How about URI templates?
>>>
>>> Maybe we have them as a /capabilities/templates resource:
>>>
>>>    {"templates": [
>>>       {"rel": "server_start_action",
>>>        "href": "http://example.org/v3/servers/{server_uuid}"
>>>       }
>>>    ]}
>>>
>>> then just do:
>>>
>>>    "links": [
>>>      {"rel": "start", "template": "server_start_action"}
>>>    ]
>>>
>>> Just a thought ...
>>>
>>> Cheers,
>>> Mark.
>>>
>>>
>>> _______________________________________________
>>> OpenStack-TC mailing list
>>> OpenStack-TC at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc
>>>
>>>
>>> _______________________________________________
>>> OpenStack-dev mailing list
>>> OpenStack-dev at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>>
>>> _______________________________________________
>>> OpenStack-dev mailing list
>>> OpenStack-dev at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130528/fbe7d47a/attachment.html>