Open Stack

Ok, OpenStack ransom of success means the APIs request list is growing.
So what's the plan for self-described APIs?
Do we have a standardized solution exposing the requests' methods, 
parameters to other program to exploit?

Sure, some OpenStack APIs advertise their interface using GET method 
such as {"show api version", "/v1/"}.
Although consistent in the format but not available across all projects, 
it doesn't seem to be following a standard anyway, right?
Besides and more importantly it isn't suitable to fully expose the 
requests interfaces.

We know REST is not a standard in itself, but RESTful implementations 
make use of standards, such as HTTP, URI, JSON and XML [1]
This have brought an excellent candidate tailored for the job, the HTTP 
OPTION, please see RFC2616 [2] for more details.
Using such an approach would allow OpenStack APIs requests interfaces 
(methods, parameters and items) to be advertised to other programs.
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.
The next generation of RESTful clients could get up to date automatically.

In the meantime that happens, the only comprehensive APIs reference 
source I've found is developer.openstack.org/api-ref.html 
<http://developer.openstack.org/api-ref.html> [2].
BTW, great work Oslo Sphinx team, thank you!
The API-ref allows most of APIs interfaces to be partly generated using 
web crawlers.
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.

The flaws I've found:
- Missing requests from API ref: Only a few (example? Ironic: heartbeat  
POST, "/v1/heartbeat/{node_ident}")
- 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.

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.

Cheers,
Gilles

PS: In an ideal world, the API is built first and the rest upon.

[1] https://en.wikipedia.org/wiki/Representational_state_transfer
[2] https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
[3] 
http://developer.openstack.org/api-ref/baremetal/?expanded=call-a-method-detail
[4] http://developer.openstack.org/api-ref/baremetal/?expanded=id73-detail

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