Open Stack

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

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

On 02/02/2015 02:51 PM, Stefano Maffulli wrote:
On Fri, 2015-01-30 at 23:05 +0000, 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20150213/8c2547ed/attachment.html>