Open Stack

On 1/13/15, 04:16, "Chris Dent" <chdent at redhat.com> wrote:

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

Yes, I misunderstood you. Sorry about that.

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

So if the schemas are part of the test suite (enforcing them and ensuring
that the endpoints return responses compliant with it) then we’ll catch
changes that aren’t documented by the schema. Using the schema (with its
examples) to document the endpoint’s request/response cycle means that the
documentation of what the endpoint expects and what it returns is at the
very least technically correct. Good descriptions of the endpoints and the
data in the schema will only improve the generated documentation. I’m not
sure how that doesn’t reduce the overhead of writing documentation for the
API.

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

That’s a good question. I’m not sure how we’ll get people to adopt it
instead of using jsonchema directly or warlock or something else that
provides similar (policing) functionality. One thing that would probably
ease adoption would be the ability to import/auto-write definitions based
on existing jsonschema definitions.

As for differences from SOAP/WSDL: This doesn’t add any overhead to the
message parsing and is not significantly different from how we already use
jsonschema. You can already request /v2/schema/images from glance if you
want to validate the data you receive from /v2/images, there’s no
requirement that says you have to though.

In essence the idea of this tooling is to provide tooling that the
services can each use that will be a net improvement and more feature-ful
than what it already uses. As a group, it seems like most projects have
realized the value of using jsonschema/warlock/etc. and acknowledges it’s
a net benefit. Why not just build atop that with better tooling that
generates documentation for the service and is in a relatively readable
format? It would also be simple enough to support schemas written and
stored as JSON for the initial conversion if the change from JSON -> YAML
bothers enough people.
>