Open Stack

+1 Couldn't agree more.

Christopher Armstrong <chris.armstrong at rackspace.com> wrote:



On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes <jaypipes at gmail.com<mailto:jaypipes at gmail.com>> wrote:
Hi all,

One of the most important aspects in the early stages of Solum development will be the consensus building and stabilization of the Solum API specification. A solid API spec aid in the speeding up the pace of innovation in the Solum contributor community.

One of the aspects of the Keystone development process that I think is a big benefit is the separate source repository that stores the OpenStack Identity API specifications:

https://github.com/openstack/identity-api

When new versions of the API specification are debated or new extensions are proposed, patches are made to the specification markdown documents and reviewed in the exact same manner that regular code is on the https://review.openstack.org Gerrit site. Contributors are free to annotate the proposed changes to the API specification in the same way that they would make inline code comments on a regular code review. Here's an example for a proposed change that I recently made:

https://review.openstack.org/#/c/54215/10

I'd like to propose that Solum do the same: have a separate source repository for the API specification.

Thoughts?
-jay


I like this idea. I'd also propose that the format of the specification be something machine-readable, such as API-Blueprint (a simple subset of markdown, apiblueprint.org<http://apiblueprint.org>, also what apiary uses, if you've ever seen that) or RAML (a more structured YAML-based syntax, raml.org<http://raml.org>). API-Blueprint is closer to what the keystone document uses.

Making the documentation machine-readable means that it's much easier to verify that, in practice, the implementation of an API matches its specification and documentation, which is a problem that plagues many OpenStack projects right now.

--
IRC: radix
Christopher Armstrong
Rackspace
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20131102/c6f5da4a/attachment.html>