On Tue, 13 Jan 2015, Ian Cordasco wrote:
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:
Your response below suggests that I didn't make the point above about
how I think this is "a reasonable idea" strongly enough. My comments
were not to disparage the idea but rather to start applying some flesh
on the bare bones of some concerns that might arise as people try to apply
the idea.
* 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.
Yes, that restates the problem nicely: all code always has the problem
I stated: documentation (in whatever form) is highly likely to get out
of sync with implementations. You made some motions towards ways to
guard against this problem when you described how tests and
documentation can be interlinked. Sounds great! But it doesn't
entirely ameliorate the concern.
* 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).
We don't try to achieve HATEOAS _now_ but why should it be off the
radar for things we do in the future? There's a frequent tension in
the API discussions between describing and validating the existing
APIs and describing a target for future improvements. I think we should
be doing both. There could be room for discussion about increased
hypermedia. It is _one_ of the ways to allow robust longevity of APIs. I
don't personally want to open that can of worms if it has been opened
many times before, but it is worth noting the option as it provides a
much different technique for addressing the concerns about versioning
and documentation.
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).
What I was expressing in that paragraph was a bit of allegoric
thinking: This thing you're suggesting smells a bit like these other
things that although they sounded like good ideas failed to have
long-lived success all for much the same reason.
I guess I should have made the implicit questions explicit: How is this
formalism that you are suggesting different from those? How can we guard
against the social tendency of devs who have freedom of choice to choose
tools that are embedded in the ethic of "easy to diddle"? How can we
ensure that the tools we create fall on that side of things?
--
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
