Open Stack

On Tue, 13 Jan 2015, Ian Cordasco wrote:

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

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