<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">Hi all,<br>
<br>
I am currently looking at the Ironic API and was pointed towards
the etherpad here:
<meta http-equiv="content-type" content="text/html;
charset=ISO-8859-1">
<a
href="https://etherpad.openstack.org/api-version-discovery-proposal">https://etherpad.openstack.org/api-version-discovery-proposal</a><br>
<br>
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:
<meta http-equiv="content-type" content="text/html;
charset=ISO-8859-1">
<a href="https://gist.github.com/mtaylor/5663143">https://gist.github.com/mtaylor/5663143</a>//.
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.<br>
<br>
What are your thoughts? Is there some use case where this
approach will not work.<br>
<br>
Regards<br>
Martyn<br>
<br>
On 22/05/13 19:53, Gabriel Hurley wrote:<br>
</div>
<blockquote
cite="mid:a16779febdfd477ab943e130f05dd43d@BN1PR05MB044.namprd05.prod.outlook.com"
type="cite">
<pre wrap="">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
</pre>
<blockquote type="cite">
<pre wrap="">-----Original Message-----
From: John Dickinson [<a class="moz-txt-link-freetext" href="mailto:me@not.mn">mailto:me@not.mn</a>]
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
<a class="moz-txt-link-freetext" href="http://swift/v1/capabilities/">http://swift/v1/capabilities/</a>). 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 <a class="moz-txt-link-rfc2396E" href="mailto:Gabriel.Hurley@nebula.com"><Gabriel.Hurley@nebula.com></a>
wrote:
</pre>
<blockquote type="cite">
<pre wrap="">It seems like there's some reasonable support for going in the direction of
</pre>
</blockquote>
<pre wrap="">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?
</pre>
<blockquote type="cite">
<pre wrap="">
- Gabriel
From: Dolph Mathews [<a class="moz-txt-link-freetext" href="mailto:dolph.mathews@gmail.com">mailto:dolph.mathews@gmail.com</a>]
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
</pre>
</blockquote>
<pre wrap=""><a class="moz-txt-link-rfc2396E" href="mailto:mark.washenberger@markwash.net"><mark.washenberger@markwash.net></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">I'm not sure that is really 100% of the problem here, but we are definitely
</pre>
</blockquote>
<pre wrap="">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.
</pre>
<blockquote type="cite">
<pre wrap="">
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
</pre>
</blockquote>
<pre wrap="">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.
</pre>
<blockquote type="cite">
<pre wrap="">
For some reason I cannot remember, we neglected to realize that link
</pre>
</blockquote>
<pre wrap="">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.
</pre>
<blockquote type="cite">
<pre wrap="">
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
</pre>
</blockquote>
<pre wrap="">avoid namespace pollution.
</pre>
<blockquote type="cite">
<pre wrap="">
{
"entity": {
"id": string,
"name": string
"links": {
"self": url,
"related_collection": url
}
}
}
<a class="moz-txt-link-freetext" href="https://github.com/openstack/identity-api/blob/master/openstack-identi">https://github.com/openstack/identity-api/blob/master/openstack-identi</a>
ty-api/src/markdown/identity-api-v3.md#create-an-entity
which is a bit more compressed.
[1] - <a class="moz-txt-link-freetext" href="http://tools.ietf.org/html/draft-zyp-json-schema-03">http://tools.ietf.org/html/draft-zyp-json-schema-03</a>
[2] - <a class="moz-txt-link-freetext" href="http://tools.ietf.org/html/draft-zyp-json-schema-03#section-6.1">http://tools.ietf.org/html/draft-zyp-json-schema-03#section-6.1</a>
On Wed, May 8, 2013 at 10:33 PM, Mark McLoughlin
</pre>
</blockquote>
<pre wrap=""><a class="moz-txt-link-rfc2396E" href="mailto:markmc@redhat.com"><markmc@redhat.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">On Wed, 2013-05-08 at 18:59 +0000, Gabriel Hurley wrote:
</pre>
<blockquote type="cite">
<blockquote type="cite">
<pre wrap="">-----Original Message-----
From: Vishvananda Ishaya [<a class="moz-txt-link-freetext" href="mailto:vishvananda@gmail.com">mailto:vishvananda@gmail.com</a>]
Sent: Tuesday, May 07, 2013 3:44 PM
</pre>
</blockquote>
<pre wrap="">
</pre>
<blockquote type="cite">
<pre wrap="">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":<a class="moz-txt-link-rfc2396E" href="http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980">"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
008cfa10b980"</a>},
{"rel": "start",
"href":<a class="moz-txt-link-rfc2396E" href="http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980/start">"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
008cfa10b980/start"</a>
"feature": "os-start-stop"},
{"rel": "stop",
"href":<a class="moz-txt-link-rfc2396E" href="http://example.org/v3/servers/009e9aca-b765-11e2-855a-008cfa10b980/stop">"http://example.org/v3/servers/009e9aca-b765-11e2-855a-
008cfa10b980/stop"</a>
"feature": "os-start-stop"}.
]
}
}
</pre>
</blockquote>
<pre wrap="">
Tht perfectly illustrates my biggest concern with doing this on a
per-resource basis.
</pre>
</blockquote>
<pre wrap="">
Per-resource does allow you to expose whether a user has permission to
perform an action, though.
</pre>
<blockquote type="cite">
<pre wrap=""> 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.
</pre>
</blockquote>
<pre wrap="">
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": <a class="moz-txt-link-rfc2396E" href="http://example.org/v3/servers/{server_uuid}">"http://example.org/v3/servers/{server_uuid}"</a>
}
]}
then just do:
"links": [
{"rel": "start", "template": "server_start_action"}
]
Just a thought ...
Cheers,
Mark.
_______________________________________________
OpenStack-TC mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-TC@lists.openstack.org">OpenStack-TC@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-tc</a>
_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<pre wrap="">
_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<pre wrap="">
_______________________________________________
OpenStack-dev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a>
</pre>
</blockquote>
<br>
</body>
</html>