Open Stack

On 02/12/2015 01:08 PM, Jay Pipes wrote:
> 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

+1 I think the way to go would be:

"We suggest (pretty please) that you comply with RFCs 7230-5 and if you
have any questions ask us. Also here are some examples of usage that
is/isn't RFC compliant for clarity"

-- 
Ryan Brown / Software Engineer, Openstack / Red Hat, Inc.