Open Stack

On 02/12/2015 01:01 PM, Chris Dent 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?

I think it's definitely the role of the API WG to identify places in our 
API implementations that are not following "the rules", yes.

I think paraphrasing particular parts of RFCs would be my preference, 
along with examples of bad or incorrect usage.

Best,
-jay