Open Stack

On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes <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, also what apiary uses, if you've ever seen
that) or RAML (a more structured YAML-based syntax, 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/25555980/attachment.html>