Open Stack

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