[openstack-dev] The API WG mission statement

michael mccune msm at redhat.com
Tue Feb 3 16:07:51 UTC 2015


On 02/02/2015 08:58 AM, Chris Dent wrote:
> This is pretty good but I think it leaves unresolved the biggest
> question I've had about this process: What's so great about
> converging the APIs? If we can narrow or clarify that aspect, good
> to go.

+1, really good point

> The implication with your statement above is that there is some kind
> of ideal which maps, at least to some extent, across the rather
> diverse set of resources, interactions and transactions that are
> present in the OpenStack ecosystem. It may not be your intent but
> the above sounds like "we want all the APIs to be kinda similar in
> feel" or "when someone is using an OpenStack-related API they'll be
> able to share some knowledge between then with regard to how stuff
> works".
>
> I'm not sure how realistic^Wuseful that is when we're in an
> environment with APIs with such drastically different interactions
> as (to just select three) Swift, Nova and Ceilometer.

even though there are drastically different interactions among the 
services of openstack, i think there is some value to those apis having 
a similar feel to them. i always find it to be useful when i can 
generally infer some of the details about an api by it's general 
structure/design. imo, the guidelines will help to bake in some of these 
inferences.

unfortunately, baking a "feel" into an api guideline is more of an 
analog task. so, very difficult to codify... but i can dream =)

>
> We've seen this rather clearly in the recent debates about handling
> metadata.
>
> Now, there's nothing in what you say above that actually straight
> out disagrees with my response, but I think there's got to be some
> way we can remove the ambiguity or narrow the focus. The need to
> remove ambiguity is why the discussion of having a mission statement
> came up.

+1

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

mike



More information about the OpenStack-dev mailing list