Open Stack

On Mon, 12 Jan 2015, Ian Cordasco wrote:

> This worked extremely well in my experience and helped improve development
> time for new endpoints and new endpoint versions. The documentation was
> also heavily used for the multiple internal clients for that API.

This idea of definition formats seems like a reasonable idea (see my
response to Anne over on the gabbi thread[1]) but I worry about a few
things:

* Unless you're auto generating the code from the formal defition you
   run into a lot of opportunities for truth to get out of sync between
   the definition and the implementation.

* Ugh, auto generated code. Magic. Ew. This is Python by golly!

* Specifying every single endpoint or many endpoints is just about as
   anti-REST as you can get if you're a HATEOAS believer. I suspect
   this line of concern is well-trod ground and not worth bringing back
   up, but all this stuff about versioning is meh and death to client
   diversity.

* Yes to this:
> The problem with building something like this /might/ be tying it in to
> the different frameworks used by each of the services but on the whole
> could be delegated to each service as it looks to integrate.

All that said, what you describe in the following would be nice if it
can be made true and work well. I suspect I'm still scarred from WSDL
and company but I'm not optimistic that culturally it can be made to
work. Simple HTTP APIs wins over SOAP and pragmatic HTTP wins over true
REST and JSON wins over XML because all of the latter have a flavor of
flexibility and easy to diddle that does not exist in the former. The
problem is social, not technical.

> From my personal perspective, YAML is a nice way to document all of this
> data, especially since it’s a format that most any language can parse. We
> used these endpoint definitions to simply how we wrote clients for the API
> we were developing and I suspect we could do something similar with the
> existing clients. It would also definitely help any new clients that
> people are currently writing. The biggest win for us would be having our
> documentation mostly auto-generated for us and having a whole suite of
> tests that would check that a real response matches the schema. If it
> doesn’t, we know the schema needs to be updated and then the docs would be
> automatically updated as a consequence. It’s a nice way of enforcing that
> the response changes are documented as they’re changed.

[1] http://lists.openstack.org/pipermail/openstack-dev/2015-January/054287.html

-- 
Chris Dent tw:@anticdent freenode:cdent
https://tank.peermore.com/tanks/cdent