Open Stack

On 2/12/15, 12:01, "Chris Dent" <chdent at redhat.com> wrote:

>
>I meant to get to this in today's meeting[1] but we ran out of time
>and based on the rest of the conversation it was likely to lead to a
>spiral of different interpretations, so I thought I'd put it up here.
>
>$SUBJECT says it all: When writing guidelines to what extent do we
>think we should be recapitulating the HTTP RFCs and restating things
>said there in a form applicable to OpenStack APIs?
>
>For example should we say:
>
>     Here are some guidelines, for all else please refer to RFCs
>     7230-5.
>
>Or should we say something like:
>
>     Here are some guidelines, including:
>
>     If your API has a resource at /foo which responds to an authentic
>     request with method GET but not with method POST, PUT, DELETE or
>PATCH
>     then when an authentic request is made to /foo that is not a GET it
>must
>     respond with a 405 and must include an Allow header listing the
>     currently support methods.[2]
>
>I ask because I've been fleshing out my gabbi testing tool[3] by running
>it against a variety of APIs. Gabbi makes it very easy to write what I
>guess the officials call negative tests -- Throw some unexpected but well-
>formed input, see if there is a reasonable response -- just by making
>exploratory inquiries into the API and then traversing the discovered
>links
>with various methods and content types.
>
>What I've found is too often the response is not reasonable. Some of
>the problems arise from the frameworks being used, in other cases it
>is the implementing project.
>
>We can fix the existing stuff in a relatively straightforward but
>time consuming fashion: Use tools like gabbi to make more negative tests,
>fix the bugs as they come up. Same as it ever was.
>
>For new stuff, however, does there need to be increased awareness of
>"the rules" and is it the job of the working group to help that
>increasing along?
>
>[1]
>http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.0
>0.html
>
>[2] This is a paraphase of:
>http://tools.ietf.org/html/rfc7231#section-6.5.5
>
>[3] https://pypi.python.org/pypi/gabbi
>
>-- 
>Chris Dent tw:@anticdent freenode:cdent
>https://tank.peermore.com/tanks/cdent
>
>__________________________________________________________________________
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

So that particular problem you mention is an issue with the Routes
package. It assumes you will define very (method, route) that you wish to
handle and it’ll 404 everything else (because no definition was found). If
we used better (slightly higher level) frameworks, we probably wouldn’t
have to concern ourselves with defining those combinations for things that
/should/ intuitively return a 405. Miguel has run into this before and
only recently was able to fix it in one of the projects.

That said, I think that I’ve been referencing RFCs a lot lately in
discussions with people on topics. I’ll happily constantly
restate/recapitulate the relevant parts of each RFC I need to reference in
a discussion but I’ve been trying to decide how much of it we should
emphasize.

I worry that if we put too much emphasis on one part of an RFC, developers
will expect the rest of it to be less important and unnecessary to follow.
Further, there are more relevant RFCs than just 7230-7235.

3986 is relevant from a URI perspective and what exactly is allowed in
what part of a URI and what expectations application developers who handle
unquoting (a.k.a., percent-decoding) some part of the URI should expect
about what always will be encoded and what /may/ be encoded.

4627 defines exactly what three character sets are allowed to be used for
a JSON body that’s returned with a Content-Type of ‘application/json’.

For people who want to accept multipart/form-data bodies with filenames
(or other metadata) that is in a non-latin-1 character set, they’ll need
to read RFC 2231 to learn how to properly parse and handle an upload that
correctly handles those names.

For people wanting to encode non-latin-1 character sets in regular
request/response headers, they’ll need to read 5987.

Give me enough time and I could probably point you at the rest of the RFCs
that I’ve read while working on requests. That said, expecting everyone to
read each and every one of these RFCs is also unreasonable (especially the
new HTTP/1.1 RFCs of which 7238 is also being added presently to define
the behaviour of a 308 redirect.

There’s a lot to read, but it really is necessary to know the standards so
more discussions like the one that took place on
https://review.openstack.org/#/c/141229/ don’t happen. It seems to me many
of our APIs have been built without proper research into standards for how
they should be built.

Paraphrasing is nice, but pointing people towards good existing tools
would be nicer.

Cheers,
Ian