On 1/12/15, 17:21, "Chris Dent" <chd...@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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
