Open Stack

On 1/12/15, 17:21, "Chris Dent" <chdent at redhat.com> wrote:

>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.

The /documentation/ was used by /developers/ to build the internal
clients. It was also used by the front-end developers who built the
user-facing interface that consumed these APIs.

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

I’m not suggesting auto-generated code (although that’s always a
*possibility*).

>* 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.

Except that we don’t even try to achieve HATEOAS (or at least the
OpenStack APIs I’ve seen don’t). If we’re being practical about it, then
the idea that we have a contract between the API consumer (also read:
user) and the server makes for a drastic simplification. The fact that the
documentation is auto-generated means that writing tests with gabbi would
be so much simpler for you (than waiting for people familiar with it to
help you).

>* 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.

Well I’ve only seen it used with JSON, so I’m not sure where you got XML
from (or SOAP for that matter). Besides, this is a tool that will help the
API developers more than it will hurt them. In-tree definitions in a
(fairly) human readable format that clearly states what is accepted and
generated by an endpoint means that scrutinizing Pecan and WSME isn’t
necessary (until you start writing the endpoint itself).

>
>> 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.htm
>l
>
>-- 
>Chris Dent tw:@anticdent freenode:cdent
>https://tank.peermore.com/tanks/cdent