<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p>Ok, OpenStack ransom of success means the APIs request list is
growing.<br>
So what's the plan for self-described APIs? <br>
Do we have a standardized solution exposing the requests' methods,
parameters to other program to exploit?</p>
<p>Sure, some OpenStack APIs advertise their interface using GET
method such as {"show api version", "/v1/"}.<br>
Although consistent in the format but not available across all
projects, it doesn't seem to be following a standard anyway,
right?<br>
Besides and more importantly it isn't suitable to fully expose the
requests interfaces. <br>
</p>
<p>We know REST is not a standard in itself, but RESTful
implementations make use of standards, such as HTTP, URI, JSON and
XML [1]<br>
This have brought an excellent candidate tailored for the job, the
HTTP OPTION, please see RFC2616 [2] for more details.<br>
Using such an approach would allow OpenStack APIs requests
interfaces (methods, parameters and items) to be advertised to
other programs.<br>
By offering a new level of API automation, almost over are the
days of tedious work for every OpenStack client of creating or
adding every interface corresponding code and its test code. <br>
The next generation of RESTful clients could get up to date
automatically.<br>
</p>
<p>In the meantime that happens, the only comprehensive APIs
reference source I've found is <a
href="http://developer.openstack.org/api-ref.html">developer.openstack.org/api-ref.html</a>
[2].<br>
BTW, great work Oslo Sphinx team, thank you!<br>
The API-ref allows most of APIs interfaces to be partly generated
using web crawlers.<br>
Unfortunately, there a still missing projects from the reference
so the rest still has to be manually produced and for the one
automatically generated there are various flaws which require
manual intervention. <br>
</p>
The flaws I've found:<br>
- Missing requests from API ref: Only a few (example? Ironic:
heartbeat POST, "/v1/heartbeat/{node_ident}")<br>
- API Inconsistencies: For instance, the call a method for Node
Vendor [3] or Driver Vendor [4] Passthru is the same, which create a
conflict for REST Clients.<br>
<br>
So again, the API-ref is great and allow to cover the requests list
but that's not good enough for automation where the requests
capabilities need to be advertised properly and comprehensively
through a standard, such as the HTTP Option. Actually the API-ref
could benefit from it too and consume the latter.<br>
<br>
Cheers,<br>
Gilles<br>
<p>PS: In an ideal world, the API is built first and the rest upon.<br>
</p>
<p>[1] <a class="moz-txt-link-freetext" href="https://en.wikipedia.org/wiki/Representational_state_transfer">https://en.wikipedia.org/wiki/Representational_state_transfer</a><br>
[2] <a class="moz-txt-link-freetext" href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html</a><br>
[3]
<a class="moz-txt-link-freetext" href="http://developer.openstack.org/api-ref/baremetal/?expanded=call-a-method-detail">http://developer.openstack.org/api-ref/baremetal/?expanded=call-a-method-detail</a><br>
[4]
<a class="moz-txt-link-freetext" href="http://developer.openstack.org/api-ref/baremetal/?expanded=id73-detail">http://developer.openstack.org/api-ref/baremetal/?expanded=id73-detail</a></p>
</body>
</html>