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
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
