settingsLogin | Registersettings

[openstack-dev] [api] Forming the API Working Group

0 votes

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

To avoid bike shedding over the name of the working group, I decided to title the wiki page API Working Group. Simple, to the point, and avoids loaded terms like standards, best practices, guidelines, conventions, etc.

The point isn?t what we name it. The point is what action we take about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if this is the way things are. They?re not. The wiki page is just a starting point. If something was missed, add it. If something can be improved, improve it. Let?s try to keep it simple though.

I invite everyone who chimed in on the original thread [1] that kicked this off to add themselves as a member committed to making the OpenStack APIs better. I?ve Cc?d everyone who asked to be kept in the loop.

I already see some cross project summit topics [2] on APIs. But frankly, with the number of people committed to this topic, I?d expect there to be more. I encourage everyone to submit more API related sessions with better descriptions and goals about what you want to achieve in those sessions.

Regards,
Everett

[1] http://lists.openstack.org/pipermail/openstack-dev/2014-September/046850.html
[2] https://etherpad.openstack.org/p/kilo-crossproject-summit-topics

asked Oct 8, 2014 in openstack-dev by Everett_Toews (4,200 points)   3 4
retagged Feb 25, 2015 by admin

29 Responses

0 votes

Hi Everett,

Great to see things moving with the API Working Group!

On Thu, Oct 9, 2014 at 9:35 AM, Everett Toews <everett.toews at rackspace.com>
wrote:

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

To avoid bike shedding over the name of the working group, I decided to
title the wiki page API Working Group. Simple, to the point, and avoids
loaded terms like standards, best practices, guidelines, conventions, etc.

The point isn?t what we name it. The point is what action we take about
it. I propose the deliverables in the API WG wiki page.

I agree with what you've written on the wiki page. I think our priority
needs to be to flesh out
https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines
so we have something to reference when reviewing specs. At the moment I see
that document as something anyone should be able to document a project's
API convention even if they conflict with another project for the moment.
Once we've got a fair amount of content we can start as a group resolving
any conflicts.

Speaking of the wiki page, I wrote it very matter-of-factly. As if this is
the way things are. They?re not. The wiki page is just a starting point. If
something was missed, add it. If something can be improved, improve it.
Let?s try to keep it simple though.

One problem with API WG members reviewing spec proposals that affect the
API is finding the specs in the first place across many different projects
repositories.

I invite everyone who chimed in on the original thread [1] that kicked
this off to add themselves as a member committed to making the OpenStack
APIs better. I?ve Cc?d everyone who asked to be kept in the loop.

I already see some cross project summit topics [2] on APIs. But frankly,
with the number of people committed to this topic, I?d expect there to be
more. I encourage everyone to submit more API related sessions with better
descriptions and goals about what you want to achieve in those sessions.

Yea if there is enough content in the API guidelines then perhaps some time
can be spent on working on resolving any conflicts in the document so
projects know what direction to head in.

Regards,

Chris
-------------- next part --------------
An HTML attachment was scrubbed...
URL:

responded Oct 10, 2014 by Christopher_Yeoh (8,400 points)   1 3 4
0 votes

Thanks for getting this going, Everett! Comments inline...

On 10/08/2014 07:05 PM, Everett Toews wrote:
https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

yay! :)

To avoid bike shedding over the name of the working group, I decided
to title the wiki page API Working Group. Simple, to the point, and
avoids loaded terms like standards, best practices, guidelines,
conventions, etc.

Yup, ++

The point isn?t what we name it. The point is what action we take
about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

The wiki content looks fine, with the exception that I really do feel
the working group needs to have some ability to review and enforce
consistency within proposed REST APIs. The wording right now is:

"The API WG is focused on creating guidelines for the APIs"

which of course is fine, but I think that the Technical Committee should
essentially grant the working group the power to enforce guidelines and
consistency for proposed new REST APIs -- whether it's a new REST API
version in an existing project or a REST APi for a newly-proposed
OpenStack server project.

I invite everyone who chimed in on the original thread [1] that
kicked this off to add themselves as a member committed to making the
OpenStack APIs better. I?ve Cc?d everyone who asked to be kept in the
loop.

I already see some cross project summit topics [2] on APIs. But
frankly, with the number of people committed to this topic, I?d
expect there to be more. I encourage everyone to submit more API
related sessions with better descriptions and goals about what you
want to achieve in those sessions.

Will do.

Best,
-jay

responded Oct 10, 2014 by Jay_Pipes (59,760 points)   3 11 14
0 votes

Tricky. First, I am new to OpenStack, and as such tend to want to shut-up
and listen.

Second, I have done APIs for distributed systems for over 30 years. Yes, I
got in very early. As such I am guilty of or saw lots of bad examples. Also
I found patterns that worked very well.

That said, the approach to APIs and versioning in OpenStack ... does not
make sense, to me. Seems a mess. Maybe I am wrong. Or not.

The notion of a group that offers living advice to the various OpenStack
projects on APIs is - I think - a good notion. Written guidelines are good,
to a point, but only that. Interpreting static documents has limits.

My current impression is the folk offering APIs need help. So if this
offering evaluates in the end as help, this is a good idea. :)

On Fri, Oct 10, 2014 at 9:09 AM, Jay Pipes wrote:

Thanks for getting this going, Everett! Comments inline...

On 10/08/2014 07:05 PM, Everett Toews wrote:

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

yay! :)

To avoid bike shedding over the name of the working group, I decided

to title the wiki page API Working Group. Simple, to the point, and
avoids loaded terms like standards, best practices, guidelines,
conventions, etc.

Yup, ++

The point isn?t what we name it. The point is what action we take

about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

The wiki content looks fine, with the exception that I really do feel the
working group needs to have some ability to review and enforce consistency
within proposed REST APIs. The wording right now is:

"The API WG is focused on creating guidelines for the APIs"

which of course is fine, but I think that the Technical Committee should
essentially grant the working group the power to enforce guidelines and
consistency for proposed new REST APIs -- whether it's a new REST API
version in an existing project or a REST APi for a newly-proposed OpenStack
server project.

I invite everyone who chimed in on the original thread [1] that

kicked this off to add themselves as a member committed to making the
OpenStack APIs better. I?ve Cc?d everyone who asked to be kept in the
loop.

I already see some cross project summit topics [2] on APIs. But
frankly, with the number of people committed to this topic, I?d
expect there to be more. I encourage everyone to submit more API
related sessions with better descriptions and goals about what you
want to achieve in those sessions.

Will do.

Best,
-jay

Regards, Everett


OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL:

responded Oct 12, 2014 by Preston_L._Bannister (1,700 points)   1 7
0 votes

HI all, will we have a discussion on this issun at Paris Summit?

On Sun, Oct 12, 2014 at 8:32 AM, Preston L. Bannister
wrote:

Tricky. First, I am new to OpenStack, and as such tend to want to shut-up
and listen.

Second, I have done APIs for distributed systems for over 30 years. Yes, I
got in very early. As such I am guilty of or saw lots of bad examples. Also
I found patterns that worked very well.

That said, the approach to APIs and versioning in OpenStack ... does not
make sense, to me. Seems a mess. Maybe I am wrong. Or not.

The notion of a group that offers living advice to the various OpenStack
projects on APIs is - I think - a good notion. Written guidelines are good,
to a point, but only that. Interpreting static documents has limits.

My current impression is the folk offering APIs need help. So if this
offering evaluates in the end as help, this is a good idea. :)

On Fri, Oct 10, 2014 at 9:09 AM, Jay Pipes wrote:

Thanks for getting this going, Everett! Comments inline...

On 10/08/2014 07:05 PM, Everett Toews wrote:

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

yay! :)

To avoid bike shedding over the name of the working group, I decided

to title the wiki page API Working Group. Simple, to the point, and
avoids loaded terms like standards, best practices, guidelines,
conventions, etc.

Yup, ++

The point isn?t what we name it. The point is what action we take

about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

The wiki content looks fine, with the exception that I really do feel the
working group needs to have some ability to review and enforce consistency
within proposed REST APIs. The wording right now is:

"The API WG is focused on creating guidelines for the APIs"

which of course is fine, but I think that the Technical Committee should
essentially grant the working group the power to enforce guidelines and
consistency for proposed new REST APIs -- whether it's a new REST API
version in an existing project or a REST APi for a newly-proposed OpenStack
server project.

I invite everyone who chimed in on the original thread [1] that

kicked this off to add themselves as a member committed to making the
OpenStack APIs better. I?ve Cc?d everyone who asked to be kept in the
loop.

I already see some cross project summit topics [2] on APIs. But
frankly, with the number of people committed to this topic, I?d
expect there to be more. I encourage everyone to submit more API
related sessions with better descriptions and goals about what you
want to achieve in those sessions.

Will do.

Best,
-jay

Regards, Everett


OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

--
Zhipeng Huang
Research Assistant
Mobile Ad-Hoc Network Lab, Calit2
University of California, Irvine
Email: zhipengh at uci.edu
Office: Calit2 Building Room 2402
OpenStack, OpenDaylight, OpenCompute affcienado
-------------- next part --------------
An HTML attachment was scrubbed...
URL:

responded Oct 13, 2014 by Zhipeng_Huang (6,720 points)   2 3 3
0 votes

Zhipeng Huang wrote:
HI all, will we have a discussion on this issun at Paris Summit?

I expect the API WG to propose API discussions within the "Cross-project
workshops" track and get space granted to them.

Cheers,

--
Thierry Carrez (ttx)

responded Oct 13, 2014 by Thierry_Carrez (57,480 points)   3 8 13
0 votes

Hi Thierry,

THX for the link ! So we will have the workshop on Nov 3th at Meridien
Etoile Hotel?

On Mon, Oct 13, 2014 at 8:40 PM, Thierry Carrez
wrote:

Zhipeng Huang wrote:

HI all, will we have a discussion on this issun at Paris Summit?

I expect the API WG to propose API discussions within the "Cross-project
workshops" track and get space granted to them.

https://etherpad.openstack.org/p/kilo-crossproject-summit-topics

Cheers,

--
Thierry Carrez (ttx)


OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

--
Zhipeng Huang
Research Assistant
Mobile Ad-Hoc Network Lab, Calit2
University of California, Irvine
Email: zhipengh at uci.edu
Office: Calit2 Building Room 2402
OpenStack, OpenDaylight, OpenCompute affcienado
-------------- next part --------------
An HTML attachment was scrubbed...
URL:

responded Oct 13, 2014 by Zhipeng_Huang (6,720 points)   2 3 3
0 votes

On 10/10/2014 02:05 AM, Christopher Yeoh wrote:
I agree with what you've written on the wiki page. I think our priority
needs to be to flesh out
https://wiki.openstack.org/wiki/Governance/Proposed/APIGuidelines
so we have something to reference when reviewing specs. At the moment I
see that document as something anyone should be able to document a
project's API convention even if they conflict with another project for
the moment. Once we've got a fair amount of content we can start as a
group resolving
any conflicts.

Agreed that we should be fleshing out the above wiki page. How would you
like us to do that? Should we have an etherpad to discuss individual
topics? Having multiple people editing the wiki page offering commentary
seems a bit chaotic, and I think we would do well to have the Gerrit
review process in place to handle proposed guidelines and rules for
APIs. See below for specifics on this...

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

One problem with API WG members reviewing spec proposals that affect the
API is finding the specs in the first place across many different
projects repositories.

I've said for a while now that I would love to have separate
repositories -- ala the Keystone API in the openstack/identity-api
repository -- that contains specifications for APIs in a single format
(APIBlueprint was suggested at one point, but Swagger 2.0 seems to me to
have more upside).

I also think it would be ideal to have an openstack/openstack-api repo
that would house guidelines and rules that this working group came up
with, along with examples of appropriate usage. This repo would function
very similar to the openstack/governance [1] repo that the TC uses to
flesh out proposals on community, release management, and governance
changes.

If people are OK with this idea, I will go ahead and create the repo and
add the wiki page content as the initial commit, then everyone can
simply submit patches to the document(s) using the normal Gerrit
process, and we can iterate on these things using the same tools as
other repositories.

Best,
-jay

[1]
https://review.openstack.org/#/q/status:open+project:openstack/governance,n,z

I invite everyone who chimed in on the original thread [1] that
kicked this off to add themselves as a member committed to making
the OpenStack APIs better. I?ve Cc?d everyone who asked to be kept
in the loop.

I already see some cross project summit topics [2] on APIs. But
frankly, with the number of people committed to this topic, I?d
expect there to be more. I encourage everyone to submit more API
related sessions with better descriptions and goals about what you
want to achieve in those sessions.

Yea if there is enough content in the API guidelines then perhaps some
time can be spent on working on resolving any conflicts in the document
so projects know what direction to head in.

Regards,

Chris


OpenStack-dev mailing list
OpenStack-dev at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Oct 13, 2014 by Jay_Pipes (59,760 points)   3 11 14
0 votes

On 10/10/2014 12:09 PM, Jay Pipes wrote:
Thanks for getting this going, Everett! Comments inline...

On 10/08/2014 07:05 PM, Everett Toews wrote:

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

yay! :)

To avoid bike shedding over the name of the working group, I decided
to title the wiki page API Working Group. Simple, to the point, and
avoids loaded terms like standards, best practices, guidelines,
conventions, etc.

Yup, ++

The point isn?t what we name it. The point is what action we take
about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

The wiki content looks fine, with the exception that I really do feel
the working group needs to have some ability to review and enforce
consistency within proposed REST APIs. The wording right now is:

"The API WG is focused on creating guidelines for the APIs"

which of course is fine, but I think that the Technical Committee should
essentially grant the working group the power to enforce guidelines and
consistency for proposed new REST APIs -- whether it's a new REST API
version in an existing project or a REST APi for a newly-proposed
OpenStack server project.

I think that's a great goal. I'd like to see the group earn this level
of influence based on its own merit rather than have the TC just grant
it up front. I'd say let's give the group a cycle to build up, generate
guidelines, and participate in API design reviews. I'd rather see it as
the TC making something official that was effectively already happening
in practice.

--
Russell Bryant

responded Oct 13, 2014 by Russell_Bryant (19,240 points)   2 3 8
0 votes

On 10/13/2014 11:10 AM, Russell Bryant wrote:
On 10/10/2014 12:09 PM, Jay Pipes wrote:

Thanks for getting this going, Everett! Comments inline...

On 10/08/2014 07:05 PM, Everett Toews wrote:

https://wiki.openstack.org/wiki/API_Working_Group

This is the start of the API Working Group (API WG).

yay! :)

To avoid bike shedding over the name of the working group, I decided
to title the wiki page API Working Group. Simple, to the point, and
avoids loaded terms like standards, best practices, guidelines,
conventions, etc.

Yup, ++

The point isn?t what we name it. The point is what action we take
about it. I propose the deliverables in the API WG wiki page.

Speaking of the wiki page, I wrote it very matter-of-factly. As if
this is the way things are. They?re not. The wiki page is just a
starting point. If something was missed, add it. If something can be
improved, improve it. Let?s try to keep it simple though.

The wiki content looks fine, with the exception that I really do feel
the working group needs to have some ability to review and enforce
consistency within proposed REST APIs. The wording right now is:

"The API WG is focused on creating guidelines for the APIs"

which of course is fine, but I think that the Technical Committee should
essentially grant the working group the power to enforce guidelines and
consistency for proposed new REST APIs -- whether it's a new REST API
version in an existing project or a REST APi for a newly-proposed
OpenStack server project.

I think that's a great goal. I'd like to see the group earn this level
of influence based on its own merit rather than have the TC just grant
it up front. I'd say let's give the group a cycle to build up, generate
guidelines, and participate in API design reviews. I'd rather see it as
the TC making something official that was effectively already happening
in practice.

Sure, totally fair point.

Best,
-jay

responded Oct 13, 2014 by Jay_Pipes (59,760 points)   3 11 14
0 votes

Zhipeng Huang wrote:
THX for the link ! So we will have the workshop on Nov 3th at Meridien
Etoile Hotel?

The workshops happen on the 4th (Tuesday).

--
Thierry Carrez (ttx)

responded Oct 13, 2014 by Thierry_Carrez (57,480 points)   3 8 13
...