Open Stack

On Tue, 3 Feb 2015, Everett Toews wrote:
> On Feb 3, 2015, at 10:07 AM, michael mccune <msm at redhat.com> wrote:
>> On 02/02/2015 08:58 AM, Chris Dent wrote:
>>> I think where we want to focus our attention is:
>>>
>>> * strict adherence to correct HTTP
>>> * proper use of response status codes
>>> * effective (and correct) use of a media types
>>> * some guidance on how to deal with change/versioning
>>> * and _maybe_ a standard for providing actionable error responses
>>> * setting not standards but guidelines for anything else
>>
>> really solid starting point, the last point deserves emphasis too. i
>> think we should be very mindful of the idea that these are guidelines
>> not hard standards, but i haven't heard anyone in the meetings
>> referring to them as standards. it seemed like we had consensus about
>> the "guidelines" part.
>
> It’s early days in the API WG. Coming up with a list like this at
> the outset seems overly restrictive. How does something get on the
> list? How does something get off the list? Whatever the answer, I can
> see it taking a lot of wheel spinning. I prefer to keep things a bit
> more open early on and let it evolve.

Interesting. I made that list above because I imagined it to be (and
wanted it to be) less restrictive (that is, more abstract and general)
than many of the proposed guidelines which have come across the api-wg
gerrit radar. We talk quite a bit about the content of request and
response bodies. This suprises me very much in the context of HTTP APIs
where resource representation can be so diverse[1].

Items 2-5 are essentially item 1 restated, modulo some "just do what
the rest of the world does".

Item 6 is a way of saying "we need to be sure that the _reader_
knows these are guidelines not standards". Within the group we've
certainly agreed they are guidelines but a lot of other people react
otherwise, so it's just something to be clear about.

[1] And we haven't even begun to talk about content negotiation,
which is a shame.
-- 
Chris Dent tw:@anticdent freenode:cdent
https://tank.peermore.com/tanks/cdent