Open Stack

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

After you’ve built a few clients against many of the OpenStack APIs the inconsistencies and, often times, bizarre designs decisions truly begin to grate on you and wear you down. One example is not being able to reuse parsing code in a client because these inconsistencies and bad design. It leaves you with a client that has more code than necessary and is brittle. Developer experience can be difficult to quantify and it often times it does come down to words like the “feel” of an API.

Regardless of how difficult it is to quantify, we as developers ourselves, know the joy of using a consistent and well designed library or set of libraries. The same goes for APIs. It’s analogous to UX for UIs. We’re doing DX for APIs. If we can make the APIs a joy to use, more users will build more tools on OpenStack enabling even more users to build more applications. 

This is a useful and worthwhile endeavor. 

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

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.

I’ll echo Mike’s sentiment that we should be very mindful of the idea that these are guidelines not hard standards. Hmmmm…even that might be a bit restrictive. In the Openstack HTTP error codes [1] discussion I’m getting the impression that there is a desire to make this a standard. Perhaps we need to leave the door open to setting standards in certain cases?

Everett

[1] http://lists.openstack.org/pipermail/openstack-dev/2015-January/055549.html