Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Everett Toews]

Top posting the relevant review https://review.openstack.org/#/c/161946/

Everett


On Feb 13, 2015, at 8:44 AM, michael mccune 
mailto:m...@redhat.com>> wrote:

On 02/12/2015 02:20 PM, Ryan Brown wrote:
+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"


+1, i like the idea of pointing readers towards the RFCs but also providing 
examples.

mike

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[michael mccune]

On 02/12/2015 02:20 PM, Ryan Brown wrote:

+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"



+1, i like the idea of pointing readers towards the RFCs but also 
providing examples.


mike

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Chris Dent]

On Thu, 12 Feb 2015, Ian Cordasco wrote:


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.


For sake of completeness:

* I found it in general in WSME, and made a pending fix[1]
* It's easy to make happen in Pecan if you're not careful.

In my experience it is actually easier to ensure good 404 and 405
behavior using a dispatcher that is very explicit about matching
(method, route) tuples with handler wsgi callables and then has a
static map of where it should 404, where it should 405 and when it
405s what Allow should say. For that I like selector[2]. Things that
"want to do it for you" are opaque and have to guess, guessing leads
to errors.

But that's not really on topic. Maybe another time?

[long list of relevant RFCs snipped for brevity]

Yes there are a lot of them, and I agree we shouldn't make everyone
read all of them, we'd never get back to the task at hand.

I _think_ what you're saying is that you're +5 on the need to
paraphrase but wish we had better tools. That suggests at least in
the short term we need to be doing some paraphrasing. The facility
with you rattled off that long list makes you a good volunteer.


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.


Yeah. Agree. That's the world we live in, isn't it?

[1] https://review.openstack.org/#/c/154066/
[2] https://pypi.python.org/pypi/selector (not very active, but
still works)

--
Chris Dent tw:@anticdent freenode:cdent
https://tank.peermore.com/tanks/cdent__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Ian Cordasco]

On 2/12/15, 12:01, "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?
>
>[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-requ...@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.

Che

Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Ryan Brown]

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.

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Jay Pipes]

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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [API] Do we need to specify "follow the HTTP RFCs"?

[Chris Dent]

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

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev