Re: [openstack-dev] The API WG mission statement

[Everett Toews]

On Feb 12, 2015, at 9:29 AM, Ryan Brown 
mailto:rybr...@redhat.com>> wrote:

On 02/10/2015 08:01 AM, Everett Toews wrote:
On Feb 9, 2015, at 9:28 PM, Jay Pipes 
mailto:jaypi...@gmail.com>
> wrote:

On 02/02/2015 02:51 PM, Stefano Maffulli wrote:
On Fri, 2015-01-30 at 23:05 +, Everett Toews wrote:
To converge the OpenStack APIs to a consistent and pragmatic RESTful
design by creating guidelines that the projects should follow. The
intent is not to create backwards incompatible changes in existing
APIs, but to have new APIs and future versions of existing APIs
converge.

It's looking good already. I think it would be good also to mention the
end-recipients of the consistent and pragmatic RESTful design so that
whoever reads the mission is reminded why that's important. Something
like:

   To improve developer experience converging the OpenStack API to
   a consistent and pragmatic RESTful design. The working group
   creates guidelines that all OpenStack projects should follow,
   avoids introducing backwards incompatible changes in existing
   APIs and promotes convergence of new APIs and future versions of
   existing APIs.

After reading all the mails in this thread, I've decided that Stef's
suggested mission statement above is the one I think best represents
what we're trying to do.

That said, I think it should begin "To improve developer experience
*by* converging" ... :)

+1

I think we could be even more explicit about the audience.

To improve developer experience *of API consumers by* converging the
OpenStack API to a consistent and pragmatic RESTful design. The working
group creates guidelines that all OpenStack projects should
follow, avoids introducing backwards incompatible changes in
existing APIs, and promotes convergence of new APIs and future versions
of existing APIs.

I’m not crazy about the term "API consumer" and could bike shed a bit on
it. The problem being that alternative terms for "API consumer" have
been taken in OpenStack land. “developer” is used for contributor
developers building OpenStack itself, “user” is used for operators
deploying OpenStack, and “end user” has too many meanings. “API
consumer” makes it clear what side of the API the working group audience
falls on.

I wouldn't mind "API user", I think it conveys intent but doesn't sound
as stilted as "API consumer”.

I read through the "#topic mission statement” [1] of the last API WG meeting. 
There is a lot of support for Stefano’s take on the mission statement. As such 
I’ve proposed the following patch to the api-wg repo with the tweak from “API 
consumer” to “API user”.

https://review.openstack.org/#/c/155911/

We’ve had a lot of discussion on it already so I think it’s time for people to 
have their final say. Let us know what you think!

Thanks,
Everett

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.00.log.html#l-17

__
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] The API WG mission statement

[Ryan Brown]

On 02/10/2015 08:01 AM, Everett Toews wrote:
> On Feb 9, 2015, at 9:28 PM, Jay Pipes  > wrote:
> 
>> On 02/02/2015 02:51 PM, Stefano Maffulli wrote:
>>> On Fri, 2015-01-30 at 23:05 +, Everett Toews wrote:
 To converge the OpenStack APIs to a consistent and pragmatic RESTful
 design by creating guidelines that the projects should follow. The
 intent is not to create backwards incompatible changes in existing
 APIs, but to have new APIs and future versions of existing APIs
 converge.
>>>
>>> It's looking good already. I think it would be good also to mention the
>>> end-recipients of the consistent and pragmatic RESTful design so that
>>> whoever reads the mission is reminded why that's important. Something
>>> like:
>>>
>>> To improve developer experience converging the OpenStack API to
>>> a consistent and pragmatic RESTful design. The working group
>>> creates guidelines that all OpenStack projects should follow,
>>> avoids introducing backwards incompatible changes in existing
>>> APIs and promotes convergence of new APIs and future versions of
>>> existing APIs.
>>
>> After reading all the mails in this thread, I've decided that Stef's
>> suggested mission statement above is the one I think best represents
>> what we're trying to do.
>>
>> That said, I think it should begin "To improve developer experience
>> *by* converging" ... :)
> 
> +1 
> 
> I think we could be even more explicit about the audience. 
> 
> To improve developer experience *of API consumers by* converging the
> OpenStack API to a consistent and pragmatic RESTful design. The working
> group creates guidelines that all OpenStack projects should
> follow, avoids introducing backwards incompatible changes in
> existing APIs, and promotes convergence of new APIs and future versions
> of existing APIs.
> 
> I’m not crazy about the term "API consumer" and could bike shed a bit on
> it. The problem being that alternative terms for "API consumer" have
> been taken in OpenStack land. “developer” is used for contributor
> developers building OpenStack itself, “user” is used for operators
> deploying OpenStack, and “end user” has too many meanings. “API
> consumer” makes it clear what side of the API the working group audience
> falls on.

I wouldn't mind "API user", I think it conveys intent but doesn't sound
as stilted as "API consumer".

> I also like dtroyer’s idea of a Tweetable mantra but I think we need to
> distill that mantra _from_ a longer mission statement. If we constrained
> the mission statement to <= 140 chars at the outset, we’d be losing
> valuable information that’s vital in communicating our intent. And if we
> can’t fully communicate our intent in a mission statement then it
> doesn’t have as much value.
> 
> Thanks,
> Everett
> 
> 
> 
> __
> 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
> 

-- 
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] The API WG mission statement

[Everett Toews]

On Feb 9, 2015, at 9:28 PM, Jay Pipes 
mailto:jaypi...@gmail.com>> wrote:

On 02/02/2015 02:51 PM, Stefano Maffulli wrote:
On Fri, 2015-01-30 at 23:05 +, Everett Toews wrote:
To converge the OpenStack APIs to a consistent and pragmatic RESTful
design by creating guidelines that the projects should follow. The
intent is not to create backwards incompatible changes in existing
APIs, but to have new APIs and future versions of existing APIs
converge.

It's looking good already. I think it would be good also to mention the
end-recipients of the consistent and pragmatic RESTful design so that
whoever reads the mission is reminded why that's important. Something
like:

To improve developer experience converging the OpenStack API to
a consistent and pragmatic RESTful design. The working group
creates guidelines that all OpenStack projects should follow,
avoids introducing backwards incompatible changes in existing
APIs and promotes convergence of new APIs and future versions of
existing APIs.

After reading all the mails in this thread, I've decided that Stef's suggested 
mission statement above is the one I think best represents what we're trying to 
do.

That said, I think it should begin "To improve developer experience *by* 
converging" ... :)

+1

I think we could be even more explicit about the audience.

To improve developer experience *of API consumers by* converging the OpenStack 
API to a consistent and pragmatic RESTful design. The working group creates 
guidelines that all OpenStack projects should follow, avoids introducing 
backwards incompatible changes in existing APIs, and promotes convergence of 
new APIs and future versions of existing APIs.

I’m not crazy about the term "API consumer" and could bike shed a bit on it. 
The problem being that alternative terms for "API consumer" have been taken in 
OpenStack land. “developer” is used for contributor developers building 
OpenStack itself, “user” is used for operators deploying OpenStack, and “end 
user” has too many meanings. “API consumer” makes it clear what side of the API 
the working group audience falls on.

I also like dtroyer’s idea of a Tweetable mantra but I think we need to distill 
that mantra _from_ a longer mission statement. If we constrained the mission 
statement to <= 140 chars at the outset, we’d be losing valuable information 
that’s vital in communicating our intent. And if we can’t fully communicate our 
intent in a mission statement then it doesn’t have as much value.

Thanks,
Everett

__
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] The API WG mission statement

[Jay Pipes]

On 02/02/2015 02:51 PM, Stefano Maffulli wrote:

On Fri, 2015-01-30 at 23:05 +, Everett Toews wrote:

To converge the OpenStack APIs to a consistent and pragmatic RESTful
design by creating guidelines that the projects should follow. The
intent is not to create backwards incompatible changes in existing
APIs, but to have new APIs and future versions of existing APIs
converge.


It's looking good already. I think it would be good also to mention the
end-recipients of the consistent and pragmatic RESTful design so that
whoever reads the mission is reminded why that's important. Something
like:

 To improve developer experience converging the OpenStack API to
 a consistent and pragmatic RESTful design. The working group
 creates guidelines that all OpenStack projects should follow,
 avoids introducing backwards incompatible changes in existing
 APIs and promotes convergence of new APIs and future versions of
 existing APIs.


After reading all the mails in this thread, I've decided that Stef's 
suggested mission statement above is the one I think best represents 
what we're trying to do.


That said, I think it should begin "To improve developer experience *by* 
converging" ... :)


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

Re: [openstack-dev] The API WG mission statement

[Dean Troyer]

On Tue, Feb 3, 2015 at 1:19 PM, michael mccune  wrote:

> that's something i hadn't thought about, the process behind a list of this
> sort. i don't mind having this list as a starting point, but i also agree
> with Everett for the need to establish an open and transparent working
> group. i'm also a big fan of the evolutionary growth model for this effort.
>
>>
+++


> i guess this is a point we should address as well, the possibility for a
> long term path towards standards. it's a tough chicken and egg type
> situation, especially given the desire for openness and free growth. i'm
> not sure how we would best flag that standards may someday evolve out of
> the wg, or even if we need to.
>

I could see some guidelines becoming standards, it would be an easier
process than starting from scratch since a lot of the arguments have
already been had.  But it is a different set of people setting those
standards and I'm sure an additional round of editing would occur.  But
having a well-reasoned (I hope) starting point with rationale behind it is
huge.

dt

-- 

Dean Troyer
dtro...@gmail.com
__
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] The API WG mission statement

[Chris Dent]

On Tue, 3 Feb 2015, Everett Toews wrote:

On Feb 3, 2015, at 10:07 AM, michael mccune  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__
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] The API WG mission statement

[michael mccune]

On 02/03/2015 01:49 PM, Everett Toews 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.


that's something i hadn't thought about, the process behind a list of 
this sort. i don't mind having this list as a starting point, but i also 
agree with Everett for the need to establish an open and transparent 
working group. i'm also a big fan of the evolutionary growth model for 
this effort.




I’ll echo Mike’s sentiment that we should be very mindful of the idea that 
these are guidelines not hard standards. H…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?


i guess this is a point we should address as well, the possibility for a 
long term path towards standards. it's a tough chicken and egg type 
situation, especially given the desire for openness and free growth. i'm 
not sure how we would best flag that standards may someday evolve out of 
the wg, or even if we need to.


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] The API WG mission statement

[Kevin L. Mitchell]

On Tue, 2015-02-03 at 18:49 +, Everett Toews wrote:
> I’ll echo Mike’s sentiment that we should be very mindful of the idea
> that these are guidelines not hard standards. H…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?

I tend to be in the "guideline for now" camp, but I see us slowly
shifting over to establishing standards where it makes sense.  Once the
error codes discussion truly starts to converge toward consensus
(something I feel it's close to, but not quite there yet), it seems
reasonable to make it a guideline.  As far as standards go—if we go with
the idea of header addition to tell the client about the codes, it
becomes something that can easily be added to all OpenStack APIs, and
once that happens, then I can foresee it becoming a formal standard
recommended by the API WG…
-- 
Kevin L. Mitchell 
Rackspace


__
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] The API WG mission statement

[Everett Toews]

On Feb 3, 2015, at 10:07 AM, michael mccune  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. H…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


__
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] The API WG mission statement

[michael mccune]

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

__
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] The API WG mission statement

[michael mccune]

On 02/02/2015 02:51 PM, Stefano Maffulli wrote:


 To improve developer experience converging the OpenStack API to
 a consistent and pragmatic RESTful design. The working group
 creates guidelines that all OpenStack projects should follow,
 avoids introducing backwards incompatible changes in existing
 APIs and promotes convergence of new APIs and future versions of
 existing APIs.



i like this, definitely a step in the right direction. i like Chris' 
comment (from a different email) about specifying _why_ convergence is 
something we are striving for, or even why it is good. i'm not sure how 
we fit that message into something this tightly crafted, but it's a nice 
consideration.


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] The API WG mission statement

[Stefano Maffulli]

On Fri, 2015-01-30 at 23:05 +, Everett Toews wrote:
> To converge the OpenStack APIs to a consistent and pragmatic RESTful
> design by creating guidelines that the projects should follow. The
> intent is not to create backwards incompatible changes in existing
> APIs, but to have new APIs and future versions of existing APIs
> converge.

It's looking good already. I think it would be good also to mention the
end-recipients of the consistent and pragmatic RESTful design so that
whoever reads the mission is reminded why that's important. Something
like:

To improve developer experience converging the OpenStack API to
a consistent and pragmatic RESTful design. The working group
creates guidelines that all OpenStack projects should follow,
avoids introducing backwards incompatible changes in existing
APIs and promotes convergence of new APIs and future versions of
existing APIs.

more or less...

/stef


__
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] The API WG mission statement

[Chris Dent]

On Fri, 30 Jan 2015, Everett Toews wrote:


To converge the OpenStack APIs to a consistent and pragmatic RESTful
design by creating guidelines that the projects should follow. The
intent is not to create backwards incompatible changes in existing
APIs, but to have new APIs and future versions of existing APIs
converge.


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.

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.

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.

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

For most of that there is prior art and/or active conversation going
on outside the OpenStack world which ought to be useful fodder.

--
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] The API WG mission statement

[Ryan Brown]

On 01/30/2015 06:18 PM, Dean Troyer wrote:
> On Fri, Jan 30, 2015 at 4:57 PM, Everett Toews
> mailto:everett.to...@rackspace.com>> wrote:
> 
> What is the API WG mission statement?
> 
> 
> It's more of a mantra than a Mission Statement(TM):
> 
> Identify existing and future best practices in OpenStack REST APIs to
> enable new and existing projects to evolve and converge.
> 

Identify existing and future pragmatic ideals in OpenStack REST APIs to
enable new and existing projects to evolve and converge.

I like it, but I'd like to get "pragmatic" in there somewhere. Just to
be clear we aren't just looking for pie-in-the-sky ideals, but ones that
can apply now/in the future.

> Tweetable, 126 chars!
> 
> Plus, buzzword-bingo-compatibile, would score 5 in my old corporate
> buzzwordlist...
> 
> dt
> 
> (Can you tell my flight has been delayed? ;)
> 
> -- 
> 
> Dean Troyer
> dtro...@gmail.com 
> 
> 
> __
> 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
> 

-- 
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] The API WG mission statement

[Jeremy Stanley]

On 2015-01-30 18:25:43 -0600 (-0600), Dean Troyer wrote:
> I'd buy that even if it costs a buzzword point.

The Vancouver summit needs "buzzword bingo" as a social event.
-- 
Jeremy Stanley

__
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] The API WG mission statement

[Dean Troyer]

On Friday, January 30, 2015, Jeremy Stanley  wrote:

> On 2015-01-30 17:18:00 -0600 (-0600),
> I'm shuddering at the anti-term "best practices" there. How about
> "ideals" instead? More shorter means more twittable too, right?
>

I'd buy that even if it costs a buzzword point.

dt



-- 
-- 
Dean Troyer
dtro...@gmail.com
__
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] The API WG mission statement

[Jeremy Stanley]

On 2015-01-30 17:18:00 -0600 (-0600), Dean Troyer wrote:
[...]
> Identify existing and future best practices in OpenStack REST APIs
> to enable new and existing projects to evolve and converge.
[...]

I'm shuddering at the anti-term "best practices" there. How about
"ideals" instead? More shorter means more twittable too, right?

(Quickly putting my brush away before someone hands me a paint can.)
-- 
Jeremy Stanley

__
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] The API WG mission statement

[Dean Troyer]

On Fri, Jan 30, 2015 at 4:57 PM, Everett Toews 
wrote:

> What is the API WG mission statement?
>

It's more of a mantra than a Mission Statement(TM):

Identify existing and future best practices in OpenStack REST APIs to
enable new and existing projects to evolve and converge.

Tweetable, 126 chars!

Plus, buzzword-bingo-compatibile, would score 5 in my old corporate
buzzwordlist...

dt

(Can you tell my flight has been delayed? ;)

-- 

Dean Troyer
dtro...@gmail.com
__
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] The API WG mission statement

[Everett Toews]

On Jan 30, 2015, at 4:57 PM, Everett Toews  wrote:

> Hi All,
> 
> Something we in the API WG keep bumping into are misconceptions around what 
> our mission really is. There’s general agreement in the WG about our mission 
> but we haven’t formalized it. 
> 
> It’s really highlighted the need for a mission statement/elevator 
> pitch/mantra that we can repeat to people who are encountering us in a review 
> or IRC meeting or whatever for the first time. Let’s keep it short and sweet, 
> 2-3 sentences max. 
> 
> What is the API WG mission statement?
> 
> Let’s discuss.
> 
> Thanks,
> Everett

Here’s my take,

To converge the OpenStack APIs to a consistent and pragmatic RESTful design by 
creating guidelines that the projects should follow. The intent is not to 
create backwards incompatible changes in existing APIs, but to have new APIs 
and future versions of existing APIs converge.

Everett


__
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] The API WG mission statement

[Everett Toews]

Hi All,

Something we in the API WG keep bumping into are misconceptions around what our 
mission really is. There’s general agreement in the WG about our mission but we 
haven’t formalized it. 

It’s really highlighted the need for a mission statement/elevator pitch/mantra 
that we can repeat to people who are encountering us in a review or IRC meeting 
or whatever for the first time. Let’s keep it short and sweet, 2-3 sentences 
max. 

What is the API WG mission statement?

Let’s discuss.

Thanks,
Everett
__
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