On Sat, Nov 2, 2013 at 4:39 PM, Jay Pipes <jaypi...@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
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
