from:"Everett Toews"

Re: [openstack-dev] [all][api] POST /api-wg/news

2017-03-09 Thread Everett Toews

> On Mar 9, 2017, at 11:52 AM, Ed Leafe <e...@leafe.com> wrote:
> 
> Greetings OpenStack community,
> 
> Today's meeting started on a heavyhearted note, as we hoisted our virtual 
> beers and gave a toast to Everett Toews, who recently had to step down from 
> his API-WG duties due to a job re-assignment.

I'm proud of everything we've accomplished to date and I know that there is a 
healthy future for the API Working Group. The API WG has made great strides in 
its mission [1]. Plus it sounds like the PTG sessions were very well attended 
and that's really heartening to hear after all of this time.

I wish the API WG all the best and it's been a pleasure working on this with 
everyone.

> For those who don't know, Everett and I started the API-WG a few years ago,

Umm...given this statement, I feel I _must_ provide some clarity.

The API WG was started by myself, Jay Pipes, and Chris Yeoh. The ball got 
rolling in this email thread [2]. One of our first artifacts was this wiki page 
[3]. The 3 of us were the original core members (I'm not sure if [4] is capable 
of displaying history). Then we started making commits to the repo [5]. I'll 
leave it as an exercise to the reader to determine who got involved, when they 
got involved, and in what capacity.

Ed has made a lot of contributions as of late and his efforts are genuinely 
appreciated. So much so that he became a core member and continues to drive the 
mission forward.

Cheers,
Everett

[1] http://specs.openstack.org/openstack/api-wg/#mission-statement
[2] 
http://lists.openstack.org/pipermail/openstack-dev/2014-September/thread.html#46482
[3] 
https://wiki.openstack.org/w/index.php?title=API_Working_Group=20141114155251=history
[4] https://review.openstack.org/#/admin/groups/
[5] http://git.openstack.org/cgit/openstack/api-wg/log/?ofs=200

__
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] [all][api] POST /api-wg/news

2017-02-07 Thread Everett Toews

On Feb 6, 2017, at 3:28 PM, Ken'ichi Ohmichi 
> wrote:

2017-02-06 6:45 GMT-08:00 Brian Rosmaita 
>:
On 2/6/17 5:51 AM, Jordan Pittier wrote:
[super-enormous snip -- Chris, Ken, and Jordan make good points, I
encourage you to read the entire thread; I just want to concentrate on
one point]

I would say we should make compromise, not solve dilemma. I can live in a
world where we sometimes allow an API change and sometimes prevent it.

+1000

I agree with Jordan.  We need to look at the context of each specific
case and decide whether a change is OK based on the details.  We've
already got the guideline that says "in general", you shouldn't change
the response code, and we respect that.  The Glance team isn't claiming
that the guideline is incorrect--we're just saying that given the
context of this specific bug (that is, it's been documented for a long
time to return a 204, all other metadefs DELETE calls are documented to
return a 204, all the other metadefs DELETE calls do in fact return a
204, etc.), it makes sense that this case is an exception.

Granting an exception here doesn't mean that the floodgates have opened
for an "anything goes" approach to API changes.  It just means that an
exception is appropriate in this particular case.  I am being a bit
disingenuous there because if an exception is appropriate in this case,
then it will be appropriate in other relevantly similar cases.  But
"relevant similarity" will include the entire context of the case, for
example, whether there was a published API contract, whether the other
similar calls behave as documented, etc.  From 10,000 meters, it looks
like what we're advocating is "It's OK to change a response code".  But
when you look more closely, our claim is that given the details of this
particular bug, it makes sense to fix it in the code and not in the docs.

To summarize, my point is that we shouldn't be worried that this case is
going to set a precedent.  It would be worrisome if it were going to set
a *bad* precedent, but when you look at the details of the situation, I
don't think it will.  So it looks to me, anyway, that a compromise is in
order here.  (In case I'm being too obscure, what I mean is: we should
agree that it's OK for the Glance team to fix this bug in the code with
patch https://review.openstack.org/#/c/420038/.)

I feel this case is very common case when we want to chang success status code.
Because I cannot find the other motivation for changing success status
code except we are finding bugs like this case.

So if accepting this case, I guess we drop the following guideline completely[1]

 The following types of changes are generally *not* considered acceptable:
  Changing which response code is returned on success.

This isn't an all or nothing proposition and I don't think it needs to be 
dropped completely. Members of an OpenStack project that want to adhere to the 
guidelines can use their judgement and take the guidance, that those types of 
changes are generally not considered acceptable, into account.

Each and every OpenStack project are themselves responsible for providing a 
good UX for their users. They need to be willing to fix genuine code bugs in 
order to improve that UX. Human judgement is used to define "genuine" in this 
case.

If they become unwilling to fix bugs because it changes some aspect of the UX 
(the API in this case) and users have to react to that change then we'll 
eventually be left with a bug-ridden foundation. I abhor backwards incompatible 
changes as much as the next dev but building on buggy code is the worst UX of 
all. (Yes, I'm the one who made the Internet Explorer analogy.)

Discussion over this particular issue is helping us form the guideline. But 
please note how I specified "Members of an OpenStack project" above. I want to 
make it clear that it is not the API WG's role to adjudicate on particular 
issues. The API WG can offer opinions, clarify the intention of a guideline, 
adjust guidelines if they're not clear, etc. The responsibility lies with the 
project to make good decisions for their users.

Regards,
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] [ironic] [API] Evolving our REST API

2016-10-21 Thread Everett Toews

On Oct 13, 2016, at 10:00 AM, Devananda van der Veen  
wrote:
> 
> So I have finalized five proposals of substantial changes we can make, that
> folks agreed were important to work on, and which I believe we can do within 
> the
> microversion framework starting immediately. Four of them will, I think, be
> fairly straight forward. The fifth, adding a /tasks/ resource, has the most
> challenges, and its own session planned.

I just want to point out some prior art for a tasks resource [1] in Glance. It 
might help inform your discussion a bit. I can understand how it will be 
challenging. If an API guideline for tasks eventually came out as a result of 
this discussion, it would reduce the challenges for future projects. ;)

Cheers,
Everett

[1] http://developer.openstack.org/api-ref/image/v2/#tasks


__
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] [all][API WG] How does one best express a time interval as an API filtering query?

2016-10-06 Thread Everett Toews


> On Oct 6, 2016, at 10:43 AM, Jeremy Stanley  wrote:
> 
> On 2016-10-06 10:30:30 -0500 (-0500), Kevin L. Mitchell wrote:
> [...]
>> Problem with that is that ':' is a valid character within an ISO date,
>> though I do like the 'between' prefix.  Now, '/' can be used if it's URL
>> encoded, but I agree that that is non-ideal.  How about a syntax
>> something like:
>> 
>>
>> ?finished_at=between:ISO_DATE_A@ISO_DATE_B_at=between:ISO_DATE_C@ISO_DATE_D
> 
> I'll admit I'm not up on the intricacies of URL expectations for
> APIs, but why not just use a comma? That's not an unusual meaning
> for it as punctuation (at least in English), and has the property
> that it's not overloading a typical field separator within either
> 8601 or HTTP encodings. (Now I've fulfilled my bikeshed quota for
> the month.)

We chatted about this at the API WG meeting today. This seems reasonable to us 
too.

?finished_at=between:ISO_DATE_A,ISO_DATE_B

@milanisko I encourage you to propose this change to the filtering guideline! 
[1]

Contributing is easy, same as any other OpenStack project. See #2 under How to 
Contribute. [2]

[1] 
https://github.com/openstack/api-wg/blob/master/guidelines/pagination_filter_sort.rst#filtering
[2] https://wiki.openstack.org/wiki/API_Working_Group#How_to_Contribute




__
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] [all][api] POST /api-wg/news

2016-09-01 Thread Everett Toews

Subject: [all][api] POST /api-wg/news

Greetings OpenStack community,

Today we were joined by Scott DAngelo (scottda) who has graciously taken over 
the liaison role for Cinder as Alex Meade steps down. Thanks for stepping up 
Scott and welcome to the API WG!

We also cleaned house today and merged the 3 guidelines below. Mike McCune made 
plans to dirty up our clean house and will begin work on one of bugs.

The meeting logs are in the usual place [5]. If you find an issue with an 
existing guideline [3] or think of one that needs to exist, make a bug [4].

# New guidelines

Nothing new this week.

# API guidelines that have been recently merged

* Add the beginning of a set of guidlines for URIs
  https://review.openstack.org/322194
* A guideline for links
  https://review.openstack.org/354266
* Clear the case if the version string isn't parsable
  https://review.openstack.org/346846

# API guidelines proposed for freeze

The following guidelines are available for broader review by interested 
parties. These will be merged in one week if there is no further feedback.

Nothing new this week.

# Guidelines currently under review [7]

Nothing new this week.

# API Impact reviews currently open

Reviews marked as APIImpact [1] are meant to help inform the working group 
about changes which would benefit from wider inspection by group members and 
liaisons. While the working group will attempt to address these reviews 
whenever possible, it is highly recommended that interested parties attend the 
API WG meetings [2] to promote communication surrounding their reviews.

To learn more about the API WG mission and the work we do, see OpenStack API 
Working Group [3].

Thanks for reading and see you next week!

[1] 
https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
[2] https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
[3] http://specs.openstack.org/openstack/api-wg/
[4]: https://bugs.launchpad.net/openstack-api-wg
[5]: http://eavesdrop.openstack.org/meetings/api_wg/
[7]: https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
__
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] [Nova][API] Need naming suggestions for "capabilities"

2016-08-25 Thread Everett Toews

[openstack-dev] [all][api] POST /api-wg/news

2016-08-11 Thread Everett Toews

Greetings OpenStack community,

Our main new topic for today was making sure that we take a more active role in 
curating the bugs that are now being kept in launchpad [4] by including review 
of those bugs in the workshopping that we do in each meeting. If you find 
issues in the existing guidelines or think a guideline is missing, make a bug.

The meeting logs are in the usual place. [5]

# New guidelines

* A guideline for links
  https://review.openstack.org/354266

# API guidelines proposed for freeze

The following guidelines are available for broader review by interested 
parties. These will be merged in one week if there is no further feedback.

* Add the beginning of a set of guidlines for URIs
  https://review.openstack.org/#/c/322194/

# Guidelines currently under review

These are guidelines that the working group are debating and working on for 
consistency and language. We encourage any interested parties to join in the 
conversation.

* Clarify backslash usage for 'in' operator
  https://review.openstack.org/#/c/353396/
* Clear the case if the version string isn't parsable
  https://review.openstack.org/#/c/346846/

# API Impact reviews currently open

Reviews marked as APIImpact [1] are meant to help inform the working group 
about changes which would benefit from wider inspection by group members and 
liaisons. While the working group will attempt to address these reviews 
whenever possible, it is highly recommended that interested parties attend the 
API-WG meetings [2] to promote communication surrounding their reviews.

To learn more about the API WG mission and the work we do, see OpenStack API 
Working Group [3].

Thanks for reading and see you next week!

[1] 
https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
[2] https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
[3] http://specs.openstack.org/openstack/api-wg/
[4]: https://bugs.launchpad.net/openstack-api-wg
[5]: http://eavesdrop.openstack.org/meetings/api_wg/
__
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] [api] APIs for exposing resource capabilities

2016-08-03 Thread Everett Toews


On Aug 3, 2016, at 12:59 AM, Ramakrishna, Deepti 
> wrote:

Hi,

I would like to bring your attention to my spec [1] (already approved) on 
capability APIs and would like to get feedback from API WG.

To summarize, I propose defining a capability API for every resource in a REST 
API where it makes sense and is needed. In the context of Cinder, we would have 
a capability API at the root resource level (GET 
/v3.x/{tenant_id}/capabilities) that would return, e.g., [“volume-backup", 
“other-capability”]. Similarly, we could have a capability API on the volume 
types resource (GET /v3.x/{tenant_id}/types/{volume_type_id}/capabilities) that 
would return all the features supported by a volume type and so on.

I believe that this API pattern solves the problem of exposing capabilities and 
could be used for enabling/disabling UI widgets on Horizon and other clients. 
This pattern cleanly translates to all OpenStack projects which all face the 
general problem.

Can you please look at the spec (and the implementation for Cinder [2]) and let 
me know if you have any feedback? I would be most interested in knowing your 
thoughts about cross-project suitability of this solution.

Thanks,
Deepti

[1] https://review.openstack.org/#/c/306930/
[2] https://review.openstack.org/#/c/350310/

I added this topic to the API WG meeting tomorrow.

https://wiki.openstack.org/wiki/Meetings/API-WG

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] [all][api] POST /api-wg/news

2016-06-30 Thread Everett Toews

Greetings OpenStack community,

A few interesting developments in the API WG this week.

The API WG reviewed the new Glance Artifact Repository (aka Glare) API [4]. The
team was already adhering to most of the API WG guidelines [3] and after some
reviews they were able to get excellent coverage of the guidelines for their
API. Kudos to the team!

Based on some new information, a couple of guildelines have been abandoned. The
"Add version discovery guideline" [5] was abandoned when we realized we have a
very high level conflict here with the microversion version discovery
guideline. The "Add guideline for Experimental APIs" [6] was abandoned when the
author decided to discuss it further and explore the alternate direction
pointed in the reviews.

# Recently merged guidelines

Nothing new in the last two weeks.

# API guidelines proposed for freeze

The following guidelines are available for broader review by interested
parties. These will be merged in one week if there is no further feedback.

None this week

# Guidelines currently under review

These are guidelines that the working group are debating and working on for
consistency and language. We encourage any interested parties to join in the
conversation.

* Get rid of the DRAFT warning at the top of guidelines
https://review.openstack.org/#/c/330687/
* Remove "Conveying error/fault information" section
https://review.openstack.org/#/c/330876/
* Add the beginning of a set of guidlines for URIs
https://review.openstack.org/#/c/322194/
* Add description of pagination parameters
https://review.openstack.org/190743

Note that some of these guidelines were introduced quite a long time ago and
need to either be refreshed by their original authors, or adopted by new
interested parties. If you're the author of one of these older reviews, please
come back to it or we'll have to mark it abandoned.

# API Impact reviews currently open

Reviews marked as APIImpact [1] are meant to help inform the working group
about changes which would benefit from wider inspection by group members and
liaisons. While the working group will attempt to address these reviews
whenever possible, it is highly recommended that interested parties attend the
API-WG meetings [2] to promote communication surrounding their reviews.

To learn more about the API WG mission and the work we do, see OpenStack API
Working Group [3].

Thanks for reading and see you next week!

[1]
https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
[2] https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
[3] http://specs.openstack.org/openstack/api-wg/
[4] https://review.openstack.org/#/c/283136/
[5] https://review.openstack.org/#/c/254895/
[6] https://review.openstack.org/#/c/273158/

Re: [openstack-dev] [nova] API changes on limit / marker / sort in Newton

2016-06-02 Thread Everett Toews


> On Jun 1, 2016, at 2:01 PM, Matt Riedemann  wrote:
> 
> Agree with Sean, I'd prefer separate microversions since it makes getting 
> these in easier since they are easier to review (and remember we make changes 
> to python-novaclient for each of these also).
> 
> Also agree with using a single spec in the future, like Sean did with the API 
> deprecation spec - deprecating multiple APIs but a single spec since the 
> changes are the same.

I appreciate that Nova has a long and storied history around it's API. 
Nonetheless, since it seems you're considering moving to  a new microversion, 
we'd appreciate it if you would consider adhering to the Sorting guideline [1] 
and helping drive consensus into the Pagination guideline [2].

Thanks,
Everett

[1] 
http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#sorting
[2] 
https://review.openstack.org/#/c/190743/21/guidelines/pagination_filter_sort.rst
__
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] [api] API-WG summit session recap

2016-05-09 Thread Everett Toews


> On May 9, 2016, at 10:12 AM, michael mccune  wrote:
> 
> Promoting the guidelines
> 
> 
> The heart of the API-WG has always been the guidelines that are produced, we 
> had a nice discussion about how we can increase the awareness and usage of 
> the guidelines.
> 
> One big request that came out of this discussion is the need to cleanup the 
> group's guideline page to make it clearer which pages are just place holders 
> and which contain guidelines.
> 
> The group talked about if, and how, we can better integrate with other 
> working groups to help create a broader network for the guidelines and better 
> APIs in general. The two main groups that were identified as possible 
> partners are the Application Ecosystem WG and the SDK WG. Although these 
> groups have different focuses than just APIs, there is certainly some room 
> for collaboration and consensus among all the groups.
> 
> There was also a strong discussion about how the group could advocate for 
> more projects to use the guidelines. The main result of this talk was the 
> idea of an API-WG related governance tag. Having this tag would make a nice 
> signal to end-users about the maturity and development status of a project's 
> APIs. Although the details are still in flux, the main criteria of a tag were 
> related to projects self-electing into the tag, and then creating a series of 
> tests that would prove how their APIs follow the guidelines, as well as 
> providing proper API documentation. This is still very much a work in 
> progress.

We've started an issue to track this at Guideline compliance doc [1]. We'd be 
interested to get feedback on the issue before forging ahead with the doc.

Thanks,
Everett

[1] https://bugs.launchpad.net/openstack-api-wg/+bug/1578728


__
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] [all][api] New API Guidelines Ready for Cross Project Review

2016-03-10 Thread Everett Toews

Hi All,

The following API guideline is ready for final review. It will be merged on 
March 18, if there's no further feedback.

1. Header non-proliferation guideline
https://review.openstack.org/#/c/280381/

Cheers,
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] [all] [api] API Working Group Refresher

2016-01-18 Thread Everett Toews


On Jan 17, 2016, at 8:56 PM, Qiming Teng 
> wrote:

On Fri, Jan 15, 2016 at 12:48:51PM +, Chris Dent wrote:

At yesterday's API Working Group meeting we decided it would be a
good idea to send out a refresher on the existence of the group,
its goals and activities. If you have interest in the improvement
and standardization of OpenStack APIs please take this as an
invitation to participate.

The group meets once a week in openstack-meeting-3 on Thursdays
alternating between 00:00 UTC and 16:00 UTC[0].

The meeting time is quite confusing based on info on the wiki. It says
that 'next' meeting would be 2016-01-28 at 00:00UTC, previous meeting
was 2016-01-14 at 16:00UTC. Do we have a meeting on 2016-01-21? What
timeslot should it be? 16:00UTC or 00:00UTC?

I updated the meeting page to have the correct next meeting at 2016-01-21 at 
00:00 UTC.

Apologies for the confusion.

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] [magnum][api] Looking for a Cross-Project Liaison for the API Working Group

2015-12-02 Thread Everett Toews

On Dec 2, 2015, at 12:32 AM, 王华 
> wrote:

Adrian,
I would like to be an alternate.

Regards
Wanghua

On Wed, Dec 2, 2015 at 10:19 AM, Adrian Otto 
> wrote:
Everett,

Thanks for reaching out. Eli is a good choice for this role. We should also 
identify an alternate as well.

Adrian

--
Adrian

> On Dec 1, 2015, at 6:15 PM, Qiao,Liyong 
> > wrote:
>
> hi Everett
> I'd like to take it.
>
> thanks
> Eli.

Great!

Eli and Wanghua, clone the api-wg repo as you would any repo and add yourselves 
to this file

http://git.openstack.org/cgit/openstack/api-wg/tree/doc/source/liaisons.json

Please make sure you use your name *exactly* as it appears in Gerrit. It should 
be the same as the name that appears in the Reviewer field on any review in 
Gerrit. Also, double check that you have only one account in Gerrit.

If you need help, just ask in #openstack-sdks where the API WG hangs out on IRC.

Cheers,
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] [magnum][api] Looking for a Cross-Project Liaison for the API Working Group

2015-12-01 Thread Everett Toews

Hello Magnumites,

The API Working Group [1] is looking for a Cross-Project Liaison [2] from the 
Magnum project.

What does such a role entail?

The API Working Group seeks API subject matter experts for each project to 
communicate plans for API updates, review API guidelines with their project’s 
view in mind, and review the API Working Group guidelines as they are drafted. 
The Cross-Project Liaison (CPL) should be familiar with the project’s REST API 
design and future planning for changes to it.

Please let us know if you're interested and we'll bring you on board!

Cheers,
Everett

[1] http://specs.openstack.org/openstack/api-wg/
[2] http://specs.openstack.org/openstack/api-wg/liaisons.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] [api] consolidate IRC change with #openstack-sdk?

2015-12-01 Thread Everett Toews

On Nov 30, 2015, at 7:58 AM, michael mccune  wrote:
> 
> On 11/30/2015 08:45 AM, Sean Dague wrote:
>> Ok, I'm going to assume with no real disagreement we're agreed here. I'm
>> moving the api-wg notifications to #openstack-sdks now -
>> https://review.openstack.org/#/c/251357/1/gerritbot/channels.yaml,cm
> 
> ok, i think we've got a few spots in the documentation that refer to 
> openstack-api. we can start the process of adjusting all those to 
> openstack-sdks.

I updated the couple of places I could find on the wiki. I also sent out a 
personalized message to everyone in the now defunct #openstack-api channel on 
Freenode.

See you in #openstack-sdks (don't forget it's plural!)

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] [all][api] New API Guidelines Ready for Cross Project Review

2015-11-13 Thread Everett Toews

Hi All,

The following API guidelines are ready for cross project review. They will be 
merged on Nov. 20 if there's no further feedback.

1. Add introduction for API micro version guideline
https://review.openstack.org/#/c/187112/

2. Add description of pagination parameters
https://review.openstack.org/#/c/190743/

3. A guideline for errors
https://review.openstack.org/#/c/167793/

Cheers,
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] [all][api] New API Guidelines Ready for Cross Project Review

2015-11-13 Thread Everett Toews


> On Nov 13, 2015, at 12:01 PM, John Dickinson <m...@not.mn> wrote:
> 
> 
> 
> On 13 Nov 2015, at 9:42, Everett Toews wrote:
> 
>> Hi All,
>> 
>> The following API guidelines are ready for cross project review. They will 
>> be merged on Nov. 20 if there's no further feedback.
>> 
>> 1. Add introduction for API micro version guideline
>> https://review.openstack.org/#/c/187112/
> 
> Specifically this patch, or the ones dependent on it? Because this specific 
> patch doesn't actually say anything.

Specifically this patch. Just looking to initially move forward in some small 
way on this.

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] [api] consolidate IRC change with #openstack-sdk?

2015-11-13 Thread Everett Toews

Please note that should be #openstack-sdks (plural) !

> On Nov 13, 2015, at 6:58 AM, Sean Dague  wrote:
> 
> The #openstack-api IRC channel is quite quiet most days. As such it's
> not something that people are regularly checking in on, or often forget
> about (I know I've been guilty of that). Plus we don't always have the
> right people in a conversation to make a decision.
> 
> I'd like to propose we drop the channel entirely and make #openstack-sdk
> the home of API working group conversations. That's where all the
> openstackclient, openstackclientconfig, and sdk conversations are
> happening. It's where the end consumers of any API WG effort are, so are
> incredibly good sounding boards for things we are doing. There is
> already a large overlap between the two channels, so just pushing
> forward on that means more critical mass for conversations around the
> whole space of a more usable API for users.
> 
> This came up at the last API WG meeting, but those are pretty low quorum
> events, so this is a thing we should definitely decide over ML instead.
> 
> Please express your feelings here and lets make it happen. :)

A little bit of data to inform the decision. I threw together a quick n' dirty 
spreadsheet [1] to see what the user overlap is like.

16 of the 39 in #openstack-api are already in #openstack-sdks.

I'm actually not super opinionated on it. But I suppose I'd lean towards 
folding it in.

Would like to hear what others in the API WG think.

Everett

[1] 
https://docs.google.com/spreadsheets/d/12i1bSIu38yLXnAiasNjb4Nzhy1yaHmVOQ3kFr1GIFIk/edit?usp=sharing
__
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] [nova][api]

2015-11-09 Thread Everett Toews

On Nov 9, 2015, at 12:29 AM, Tony Breeds  wrote:
> 
> On Fri, Nov 06, 2015 at 12:30:19PM +, John Garbutt wrote:
> 
>> Ideally, I would like us to fill out that pagination part first.
> 
> It seems the person leading this within the API-WG is AWOL so ...

A couple of patch sets were just sent. Please review!

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] [nova][api]

2015-11-06 Thread Everett Toews

On Nov 6, 2015, at 6:30 AM, John Garbutt 
> wrote:

On 6 November 2015 at 12:11, Sean Dague > 
wrote:
On 11/06/2015 04:13 AM, Salvatore Orlando wrote:
It makes sense to have a single point were response pagination is made
in API processing, rather than scattering pagination across Nova REST
controllers; unfortunately if I am not really able to comment how
feasible that would be in Nova's WSGI framework.

However, I'd just like to add that there is an approved guideline for
API response pagination [1], and if would be good if all these effort
follow the guideline.

Salvatore

[1] 
https://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html

The pagination part is just a TODO in there.

Ideally, I would like us to fill out that pagination part first.

If we can't get global agreement quickly, we should at least get a
Nova API wide standard pattern.

Am I missing something here?

When I sent my initial reply to this thread, I Cc'd the author of the 
pagination guideline at wu...@unitedstack.com. 
However, I got a bounce message so it's a bit unclear if wuhao is still working 
on this. If someone knows this person, can you please highlight this thread?

If we don't hear a response on this thread or the review, we can move forward 
another way.

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] [all][api][tc][perfromance] API for getting only status of resources

2015-11-05 Thread Everett Toews

On Nov 3, 2015, at 11:46 PM, John Griffith 
> wrote:

On Tue, Nov 3, 2015 at 4:57 PM, michael mccune 
> wrote:
On 11/03/2015 05:20 PM, Boris Pavlovic wrote:
What if we add new API method that will just resturn resource status by
UUID? Or even just extend get request with the new argument that returns
only status?

Thoughts?

not sure i understand the resource status by UUID, could you explain that a 
little more.

as for changing the get request to return only the status, can't you have a 
filter on the get url that instructs it to return only the status?

Yes, we already have that capability and it's used in a number of places.

Relevant API guideline

http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering

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] [nova][api] Pagination in thre API

2015-11-05 Thread Everett Toews

On Nov 5, 2015, at 5:44 AM, John Garbutt 
> wrote:

On 5 November 2015 at 09:46, Richard Jones 
> wrote:
As a consumer of such APIs on the Horizon side, I'm all for consistency in
pagination, and more of it, so yes please!

On 5 November 2015 at 13:24, Tony Breeds 
> wrote:

On Thu, Nov 05, 2015 at 01:09:36PM +1100, Tony Breeds wrote:
Hi All,
   Around the middle of October a spec [1] was uploaded to add
pagination
support to the os-hypervisors API.  While I recognize the use case it
seemed
like adding another pagination implementation wasn't an awesome idea.

Today I see 3 more requests to add pagination to APIs [2]

Perhaps I'm over thinking it but should we do something more strategic
rather
than scattering "add pagination here".

+1

The plan, as I understand it, is to first finish off this API WG guideline:
http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html

An attempt at an API guideline for pagination is here [1] but hasn't received 
any updates in over a month, which can be understandable as sometimes other 
work takes precedence.

Perhaps we can get that guideline moving again?

If it's becoming difficult to reach agreement on that approach in the 
guideline, it could be worthwhile to take a step back and do some analysis on 
the way pagination is done in the more established APIs. I've found that such 
analysis can be very helpful as you're moving forward from a known state.

The place for that analysis is in Current Design [2] by filling in the 
Pagination page. You can find many examples of such analysis from the Current 
Design like Sorting [3].

Cheers,
Everett

[1] https://review.openstack.org/#/c/190743/
[2] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design
[3] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting

__
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] [all] service catalog: TNG

2015-10-09 Thread Everett Toews

On Oct 9, 2015, at 9:39 AM, Sean Dague  wrote:
> 
> It looks like some great conversation got going on the service catalog
> standardization spec / discussion at the last cross project meeting.
> Sorry I wasn't there to participate.
> 
> A lot of that ended up in here (which was an ether pad stevemar and I
> started working on the other day) -
> https://etherpad.openstack.org/p/mitaka-service-catalog which is great.
> 
> A couple of things that would make this more useful:
> 
> 1) if you are commenting, please (ircnick) your comments. It's not easy
> to always track down folks later if the comment was not understood.
> 
> 2) please provide link to code when explaining a point. Github supports
> the ability to very nicely link to (and highlight) a range of code by a
> stable object ref. For instance -
> https://github.com/openstack/nova/blob/2dc2153c289c9d5d7e9827a4908b0ca61d87dabb/nova/context.py#L126-L132
> 
> That will make comments about X does Y, or Z can't do W, more clear
> because we'll all be looking at the same chunk of code and start to
> build more shared context here. One of the reasons this has been long
> and difficult is that we're missing a lot of that shared context between
> projects. Reassembling that by reading each other's relevant code will
> go a long way to understanding the whole picture.
> 
> 
> Lastly, I think it's pretty clear we probably need a dedicated workgroup
> meeting to keep this ball rolling, come to a reasonable plan that
> doesn't break any existing deployed code, but lets us get to a better
> world in a few cycles. annegentle, stevemar, and I have been pushing on
> that ball so far, however I'd like to know who else is willing to commit
> a chunk of time over this cycle to this. Once we know that we can try to
> figure out when a reasonable weekly meeting point would be.

It's likely you're already aware of it but see

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

for many examples of service catalogs from both public and private OpenStack 
clouds.

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] [all][api] New API Guidelines Ready for Cross Project Review

2015-10-08 Thread Everett Toews

Hi All,

The following API guidelines are ready for cross project review. They will be 
merged on Oct. 16 if there's no further feedback.

1. Adds an API documentation guideline document
https://review.openstack.org/#/c/214817/

2. Add http400 for nonexistent resource
https://review.openstack.org/#/c/221163/

Cheers,
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] [api][keystone][openstackclient] Standards for object name attributes and filtering

2015-09-06 Thread Everett Toews

On Sep 1, 2015, at 8:36 PM, Dolph Mathews  wrote:

> Does anyone have an example of an API outside of OpenStack that would return 
> 400 in this situation (arbitrary query string parameters)? Based on my past 
> experience, I'd expect them to be ignored, but I can't think of a reason why 
> a 400 would be a bad idea (but I suspect there's some prior art / discussion 
> out there).

Good question! I think it’s a great idea to look outside OpenStack-land to see 
what’s going on in the wider world of APIs.

One example is listing containers in the Docker API [1]. A number of other 
resources will also return a 400 if a bad parameter is used.

Everett

[1] 
https://docs.docker.com/reference/api/docker_remote_api_v1.20/#list-containers

__
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] [all][api] New API Guidelines Ready for Cross Project Review

2015-09-04 Thread Everett Toews

On Aug 27, 2015, at 10:48 AM, Everett Toews <everett.to...@rackspace.com> wrote:

> Hi All,
> 
> The following API guidelines are ready for cross project review. They will be 
> merged on Sept. 4 if there's no further feedback.
> 
> 1. Add description of pagination parameters
> https://review.openstack.org/#/c/190743/
> 
> 2. Require "OpenStack-" in headers
> https://review.openstack.org/#/c/215683/
> 
> 3. Add the condition for using a project term
> https://review.openstack.org/#/c/208264/
> 
> 4. Added note about caching of responses when using https
> https://review.openstack.org/#/c/185288/
> 
> 5. add section describing 501 common mistake
> https://review.openstack.org/#/c/183456/

API guidelines 2-5 above have been merged. Guideline 1 needs further work.

Thanks for you feedback,
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] [api] [wsme] [ceilometer] Replacing WSME with _____ ?

2015-08-28 Thread Everett Toews

On Aug 28, 2015, at 6:10 PM, Morgan Fainberg morgan.fainb...@gmail.com wrote:

 It seems like Flask has a reasonable amount of support and there is a good 
 ecosystem around it but that aside (as Jay said)... I definitely support 
 exposing the schema to the end user; making it easier for the end user to 
 validate input / model outputs for their integration with OpenStack services 
 is an important feature of whatever is selected. 
 
 I admit I am intrigued by the swagger things (and I expect to be spending 
 some serious time considering it) that Monty linked (especially relating to 
 Flask, but there is a bias as Keystone is moving to flask).

With respect to Swagger, we have a guideline [1] in flight from Anne that 
involves it for API docs.

Everett

[1] https://review.openstack.org/#/c/214817/
__
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] [all][api] New API Guidelines Ready for Cross Project Review

2015-08-27 Thread Everett Toews

Hi All,

The following API guidelines are ready for cross project review. They will be 
merged on Sept. 4 if there's no further feedback.

1. Add description of pagination parameters
https://review.openstack.org/#/c/190743/

2. Require OpenStack- in headers
https://review.openstack.org/#/c/215683/

3. Add the condition for using a project term
https://review.openstack.org/#/c/208264/

4. Added note about caching of responses when using https
https://review.openstack.org/#/c/185288/

5. add section describing 501 common mistake
https://review.openstack.org/#/c/183456/

Cheers,
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] [api][keystone][openstackclient] Standards for object name attributes and filtering

2015-08-27 Thread Everett Toews

On Aug 26, 2015, at 4:45 AM, Henry Nash hen...@linux.vnet.ibm.com wrote:

 Hi
 
 With keystone, we recently came across an issue in terms of the assumptions 
 that the openstack client is making about the entities it can show - namely 
 that is assumes all entries have a ‘name’ attribute (which is how the 
 openstack show command works). Turns out, that not all keystone entities 
 have such an attribute (e.g. IDPs for federation) - often the ID is really 
 the name. Is there already agreement across our APIs that all first class 
 entities should have a ‘name’ attribute?  If we do, then we need to change 
 keystone, if not, then we need to change openstack client to not make this 
 assumption (and perhaps allow some kind of per-entity definition of which 
 attribute should be used for ‘show’).

AFAICT, there’s no such agreement in the API WG guidelines [1].

 A follow on (and somewhat related) question to this, is whether we have 
 agreed standards for what should happen if some provides an unrecognized 
 filter to a list entities API request at the http level (this is related 
 since this is also the hole osc fell into with keystone since, again, ‘name’ 
 is not a recognized filter attribute). Currently keystone ignores filters it 
 doesn’t understand (so if that was your only filter, you would get back all 
 the entities). The alternative approach would of course be to return no 
 entities if the filter is on an attribute we don’t recognize (or even issue a 
 validation or bad request exception).  Again, the question is whether we have 
 agreement across the projects for how such unrecognized filtering should be 
 handled?

The closest thing we have is the Filtering guideline [2] but it doesn’t account 
for this particular case.

Client tool developers would be quite frustrated by a service ignoring filters 
it doesn’t understand or returning no entities if the filter isn’t recognized. 
In both cases, the developer isn’t getting the expected result but you’re 
masking the error made by the developer. 

Much better to return a 400 so the problem can be fixed immediately. Somewhat 
related is this draft [3].

Everett

[1] http://specs.openstack.org/openstack/api-wg/
[2] 
http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering
[3] https://tools.ietf.org/html/draft-thomson-postel-was-wrong-00


__
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] [Resend] [api] Who owns API versioning and deprecation policy?

2015-08-21 Thread Everett Toews

On Aug 21, 2015, at 3:13 PM, Geoff Arnold ge...@geoffarnold.com wrote:

 After reading the following pages, it’s unclear what the current API 
 deprecation policy is and who owns it. (The first spec implies that a change 
 took place in May 2015, but is silent on what and why.) Any hints? An 
 authoritative doc would be useful, something other than an IRC log or mailing 
 list reference.
 
 Geoff
 
 http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_changes.html
 
 https://wiki.openstack.org/wiki/API_Working_Group
 
 https://wiki.openstack.org/wiki/Application_Ecosystem_Working_Group

The API Working Group does. 

Guidelines for microversioning [1] and when to bump a microversion [2] are 
currently in review. Naturally your feedback is welcome.

We have yet to provide guidance on deprecation. If you’d like to create a 
guideline on deprecation, here’s How to Contribute [3]. If you want to throw 
some ideas around we’re in #openstack-api or feel free to drop by one of our 
meetings [4].

Everett

[1] https://review.openstack.org/#/c/187112/
[2] https://review.openstack.org/#/c/187896/
[3] https://wiki.openstack.org/wiki/API_Working_Group#How_to_Contribute
[4] https://wiki.openstack.org/wiki/Meetings/API-WG


__
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] [api] [all] To changes-since or not to changes-since

2015-08-10 Thread Everett Toews

On Aug 9, 2015, at 11:03 PM, hao wang 
sxmatch1...@gmail.commailto:sxmatch1...@gmail.com wrote:

Hi, stackers

Since now we have merged filtering guideline[1], is that said we should 
implement this feature according this guideline?  like this:

GET /app/items?f_updated_at=gte:some_timestamp

Do we have reached a consensus about this?

You’ll definitely want to drop the “f_” prefix from your filter name, see the 
about-to-be-merged guideline No project uses f_ prefix in filter params [1].

Everett

[1] https://review.openstack.org/#/c/198547/

__
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] [all][api] New API Guidelines ready for cross project review

2015-07-06 Thread Everett Toews

Hi All,

We have 7 API Guidelines that are ready for a final review.

1. Add section clarifying PUT vs PATCH semantics
https://review.openstack.org/#/c/183945/

2. Adding 5xx guidance
https://review.openstack.org/#/c/183698/

3. Adds a small update to tagging guidance
https://review.openstack.org/#/c/187891/

4. Add the description of GET method
https://review.openstack.org/#/c/185180/

5. Adds clarification and example to 500 guidance
https://review.openstack.org/#/c/190064/

6. add subsection around caching behavior and http
https://review.openstack.org/#/c/183523/

7. add section describing method use in http
https://review.openstack.org/#/c/189738/

If the API Working Group hasn’t received any further feedback, we’ll merge them 
on July 13.

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] [api][Solum] Request for feedback on new API resource

2015-06-23 Thread Everett Toews

On Jun 18, 2015, at 3:07 PM, Devdatta Kulkarni 
devdatta.kulka...@rackspace.commailto:devdatta.kulka...@rackspace.com wrote:

Hi, API WG team,

In Solum, recently we have been working on some changes to our REST API.

Basically, we have introduced a new resource ('app'). The spec for this has 
been accepted by Solum cores.
https://github.com/stackforge/solum-specs/blob/master/specs/liberty/app-resource.rst

Right now we have a patch for review implementing this spec:
https://review.openstack.org/#/c/185147/

If it is not too much to request, I was wondering if someone from your team can 
take a look
at the spec and the review, to see if we are not violating any of your 
guidelines.

Thank you for your help.

- Devdatta

Do you have this API documented anywhere?

Is there a spec or similar for this API change?

In our experience, it’s best to consider the API design apart from the 
implementation. The separation of concerns makes for a cleaner review and a 
better design. The Glance team did a good job of this in their Artifact 
Repository API specification [1].

Regards,
Everett

[1] https://review.openstack.org/#/c/177397/
__
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] [all][api] New API Guidelines ready for cross project review

2015-06-19 Thread Everett Toews

Hi All,

We have 3 API Guidelines that are ready for a final review.

1. Add section on filtering
https://review.openstack.org/#/c/177468/

2. http guideline expansion: background
https://review.openstack.org/#/c/181931/

3. Should not return server-side tracebacks
https://review.openstack.org/#/c/183599/

If the API Working Group hasn’t received any further feedback, we’ll merge them 
on June 26.

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] [monasca] [java]

2015-05-15 Thread Everett Toews

On May 15, 2015, at 3:49 AM, Thierry Carrez thie...@openstack.org wrote:

 Dieterly, Deklan wrote:
 We’ve seen that Swift has introduced components in Go. So, this looks like a 
 precedent for allowing other languages where deemed appropriate. Before we 
 spend many man-hours hacking on the Python components, it seems reasonable 
 to determine if there really exists a reason to do so. I’m interested in 
 soliciting any feedback from the community be it pleasant or unpleasant.
 
 Swift has not introduced components in Go. It is at the early stages of
 *exploring* the possibility of doing so, through a specific feature branch.
 
 The Technical Committee position has always been python unless there is
 a compelling reason otherwise. Every language supported increases
 fragmentation of our community and increases the CI effort. The argument
 for adding a language has to be pretty compelling to counterbalance the
 damage it does to OpenStack as a development community.
 
 In Monasca's case, there is always the possibility to stay out of the
 OpenStack tent and stay in Java. There is the possibility to rewrite
 things in Python. And there is the possibility to convince the Technical
 Committee that (1) we want Monasca featureset in so badly we would add
 Java as a supported language just so that can happen and (2) Monasca
 featureset can't be written in Python.

Not to move this discussion off-list but I feel the need to at least point out 
a highly relevant summit session.

Is it time to have more than just Python in OpenStack?
https://libertydesignsummit.sched.org/event/6bb3f4fe34a4a0236266d99a2039c963

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] [nova][cinder] can we deprecate the volume CLIs in novaclient?

2015-05-15 Thread Everett Toews

On May 15, 2015, at 10:28 AM, John Griffith 
john.griffi...@gmail.commailto:john.griffi...@gmail.com wrote:



On Thu, May 14, 2015 at 8:29 PM, Matt Riedemann 
mrie...@linux.vnet.ibm.commailto:mrie...@linux.vnet.ibm.com wrote:
This came up while talking about bug 1454369 [1].  This also came up at one 
point in kilo when we found out the volume CLIs in novaclient didn't work at 
one point and we broke the cells devstack exercises job because of it.

python-novaclient uses cinder API to handle the volume CLI rather than going to 
the nova volume API.  There are issues with this because novaclient needs a 
certain endpoint/service_type setup in the service catalog to support cinder 
v1/v2 APIs (whatever devstack sets up today).  novaclient defaults to volume 
(v1) and if you disable that in cinder then novaclient doesn't work because 
it's not using volumev2.

So like anyone might ask, why doesn't novaclient talk to nova volume APIs to do 
volume thingies and the answer is because the nova volume API doesn't handle 
all of the volume thingies like snapshots and volume types.

So I got to to thinking, why the hell are we still supporting volume operations 
via novaclient anyway?  Isn't that cinderclient's job?  Or 
python-openstackclient's job?  Can't we deprecate the volume CLIs in novaclient 
and tell people to use cinderclient instead since it now has version discovery 
[2] so that problem would be handled for us.

Since we have nova volume APIs maybe we can't remove the volume CLIs in 
novaclient, but could they be limited to just operations that the nova API 
supports and then we make novaclient talk to nova volume APIs rather than 
cinder APIs (because the nova API will talk to cinderclient which again has the 
version discovery done for us).

Or assuming we could deprecate the volume CLIs in novaclient, what would the 
timeline on deprecation be since it's not a server project with a 6 month 
release cycle?  I'm assuming we'd still have 6-12 months deprecation on a 
client like this because of all of the tooling potentially written around it.

[1] https://bugs.launchpad.net/python-novaclient/+bug/1454369
[2] https://review.openstack.org/#/c/145613/

I can't speak for the nova folks, however i do think removing the volume calls 
from novaclient seems ok.  It was always sort of left for compat I think, and 
not sure any of us really thought about just removing it.  At this point it 
probably just introduces confusion and as you're running into problems.

Seems like a good plan, and somewhat less confusing.  On a side note, might be 
some other *things* in novaclient that we could look at as well, particularly 
around networking.  

FWIW, this is already underway in jclouds-land. After a lengthy deprecation 
period (still ongoing actually), we’ll be removing the Nova volume calls but 
obviously keeping the volume attachment stuff.

Both the Nova and Cinder calls have coexisted for over a year with 
documentation pointing from Nova to Cinder. The deprecation annotations handle 
emitting warnings for the deprecated calls to increase visibility.

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] [api] Proposing Michael McCune as an API Working Group core

2015-05-14 Thread Everett Toews

Top posting to make it official...Michael McCune (elmiko) is an API Working 
Group core!

Cheers,
Everett


On May 11, 2015, at 8:57 PM, Ryan Brown rybr...@redhat.com wrote:

 On 05/11/2015 04:18 PM, Everett Toews wrote:
 I would like to propose Michael McCune (elmiko) as an API Working Group core.
 
 Not core, but +1 from me!
 
 -- 
 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


__
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] [all][api] State of the OpenStack API Working Group: Liberty Edition

2015-05-14 Thread Everett Toews

This blog post is basically a preview of our cross-project session.

http://blog.phymata.com/2015/05/14/state-of-the-api-wg-liberty-edition/


The API WG will also be busy bunch at the Summit.

1 cross-project session

  API Working Group: State of the Group [1]

2 working group sessions

  API Working Group: Working Session 1 [2]
  API Working Group: Working Session 2 [3]

2 summit sessions related to the API WG.

  APIs Matter [4]
  The Good and the Bad of the OpenStack REST APIs [5]

If you're attending the summit, we hope to see you there!

Cheers,
Everett


[1] https://libertydesignsummit.sched.org/event/e14d84514003140fe30e984027299a44
[2] https://libertydesignsummit.sched.org/event/3fe7ba65fed52540e6116f7bee2392a6
[3] https://libertydesignsummit.sched.org/event/c02c575cd390b71d5e17a3f27f6b5806
[4] https://libertydesignsummit.sched.org/event/bf6f86afe58148a96ab9d1dd0d30a554
[5] https://libertydesignsummit.sched.org/event/602a2acdca6f546cef89dc0c4356e3d8


__
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] [nova][api] Allow passing body for more API methods

2015-05-11 Thread Everett Toews

On May 11, 2015, at 1:05 PM, Dean Troyer 
dtro...@gmail.commailto:dtro...@gmail.com wrote:

On Mon, May 11, 2015 at 11:44 AM, Rosa, Andrea (HP Cloud Services) 
andrea.r...@hp.commailto:andrea.r...@hp.com wrote:
 Agreed. Violating the HTTP spec is something that should be avoided.

Actually it is not violating the HTTP spec, from RFC:
  A payload within a DELETE request message has no defined semantics;
   sending a payload body on a DELETE request might cause some existing
   implementations to reject the request.

The RFC prohibit the use of a body just for the TRACE:
 A client MUST NOT send a message body in a TRACE request.


When playing in undefined areas such as this it is best to keep in ming Jon 
Postel's RFC 1122 principle: Be liberal in what you accept, and conservative 
in what you send.

I'll put it this way:  An RFC not prohibiting something does not make it a good 
idea.  This is not how we build a robust API that developers and user can 
easily adopt.

I’m agreed that this is not a good idea. I’d also invoke the principle of least 
astonishment here. Because it’s a de facto standard (so much so that some proxy 
in the middle may alter or reject such a request), it would be surprising to 
developers to allow such requests.

REST APIs are difficult enough. Let’s avoid things with no defined semantics.

I’d comment on the review but Gerrit is having a fit so I filed a bug.

https://code.google.com/p/gerrit/issues/detail?id=3361

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] [api] Proposing Michael McCune as an API Working Group core

2015-05-11 Thread Everett Toews

I would like to propose Michael McCune (elmiko) as an API Working Group core.

Among Michael’s many fine qualities:

  * Active from the start
  * Highly available
  * Very knowledgable about APIs
  * Committed the guideline template 
  * Working on moving the API Guidelines wiki page
  * Lots of solid review work

Cheers,
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] [api] Changing 403 Forbidden to 400 Bad Request for OverQuota was: [nova] Which error code should we return when OverQuota

2015-05-06 Thread Everett Toews

On May 6, 2015, at 1:58 PM, David Kranz 
dkr...@redhat.commailto:dkr...@redhat.com wrote:

+1
The basic problem is we are trying to fit a square (generic api) peg in a round 
(HTTP request/response) hole.
But if we do say we are recognizing sub-error-codes, it might be good to 
actually give them numbers somewhere in the response (maybe an error code 
header) rather than relying on string matching to determine the real error. 
String matching is fragile and has icky i18n implications.

There is an effort underway around defining such sub-error-codes” [1]. Those 
error codes would be surfaced in the REST API here [2]. Naturally feedback is 
welcome.

Everett


[1] https://review.openstack.org/#/c/167793/
[2] https://review.openstack.org/#/c/167793/
__
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] [nova][api] API working group liaisons and responsibilities

2015-05-01 Thread Everett Toews

On Apr 30, 2015, at 9:54 AM, Jay Pipes jaypi...@gmail.com wrote:

 Hi Stackers,
 
 OK, so Matthew Gilliard and Alex Xu have volunteered to be the Nova team's 
 liaisons to the API working group. Big thank you to Matthew and Alex for 
 volunteering for this important role.
 
 I've created a wiki page [1] that details the responsibilities of these 
 liaisons. If these duties work out for Nova, we'll recommend other projects 
 pick them up.
 
 Here are the responsibilities that the Nova/API working group liaisons have:
 
 1. Monitor the active patch queue in nova (and nova-specs) and look out for 
 any patch that adds or changes the REST API
 
 2. For each patch collected in #1, determine if the constructs used in the 
 patch (or proposed spec) match the guidance currently laid out in the API 
 working group repo's guidance documents.
 
 3. If the patch does NOT match the guidance from the API working group, do a 
 code review on the patch pointing to the guidance from the API working group, 
 and ask the author to align with that guidance. Include in your research 
 patches to the API working group that may actually be in review and not 
 merged. (An example of this recently occurred with Sergey Nikitin's 
 re-proposed instance tagging spec: https://review.openstack.org/#/c/177112/. 
 See Ryan Brown's reference to an in-progress API working group guidance on 
 tagging)
 
 4. If there is NO guidance in the API working group repo for a particular 
 proposed API change or addition, the liaison should **either** create a 
 proposed patch to the API working group with guidance that clarifies the 
 missing functionality that is introduced in the new Nova patch or spec patch, 
 and bring the proposed guidance to the attention of the API working group. 
 **or** the liaison should working with a member of the API working group to 
 draft such a guideline. The liaison should mark the corresponding Nova patch 
 with a -1 Code Review vote with a link to the proposed guideline, noting that 
 the patch should be put on hold (Work In Progress) until the guideline is 
 merged.
 
 Best,
 -jay
 
 [1] https://wiki.openstack.org/wiki/Nova/APIWGLiaisons

This is great. I’ve added a link to that page from the Cross-Project Liaisons 
page [2]. I also added Matthew and Alex as liaisons there. 

giiard and alex_xu: feel free to join us in #openstack-api on freenode too!

Everett

[2] https://wiki.openstack.org/wiki/CrossProjectLiaisons#API_Working_Group
__
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] [all][api] 3 API Guidelines up for final review

2015-05-01 Thread Everett Toews

All 3 API guidelines have merged. Thanks everyone!

Everett


On Apr 22, 2015, at 2:08 PM, Everett Toews everett.to...@rackspace.com wrote:

 Hi All,
 
 We have 3 API Guidelines that are ready for a final review.
 
 1. Metadata guidelines document
 https://review.openstack.org/#/c/141229/
 
 2. Tagging guidelines
 https://review.openstack.org/#/c/155620/
 
 3. Guidelines on using date and time format
 https://review.openstack.org/#/c/159892/
 
 If the API Working Group hasn’t received any further feedback, we’ll merge 
 them on April 29.
 
 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


__
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] [api] Missing meetings this week

2015-04-27 Thread Everett Toews

Hi All,

I’ll be out the next few days and will be missing our meetings. Specifically 
the cross-project meeting [1] and our API WG meeting [2].

On the plus side I got to my action items from the last meeting and “froze” the 
3 guidelines up for review and proposed a cross-project session [3] (row 22). I 
also booked some time for us in the working group sessions at the summit.

Thanks,
Everett

[1] https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting
[2] https://wiki.openstack.org/wiki/Meetings/API-WG
[3] 
https://docs.google.com/spreadsheets/d/1vCTZBJKCMZ2xBhglnuK3ciKo3E8UMFo5S5lmIAYMCSE/edit#gid=827503418


__
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] [all][api] 3 API Guidelines up for final review

2015-04-22 Thread Everett Toews

Hi All,

We have 3 API Guidelines that are ready for a final review.

1. Metadata guidelines document
https://review.openstack.org/#/c/141229/

2. Tagging guidelines
https://review.openstack.org/#/c/155620/

3. Guidelines on using date and time format
https://review.openstack.org/#/c/159892/

If the API Working Group hasn’t received any further feedback, we’ll merge them 
on April 29.

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] [api] Minor changes to API

2015-04-21 Thread Everett Toews

On Apr 20, 2015, at 7:07 PM, Ian Wells 
ijw.ubu...@cack.org.ukmailto:ijw.ubu...@cack.org.uk wrote:

On 20 April 2015 at 15:23, Matthew Treinish 
mtrein...@kortar.orgmailto:mtrein...@kortar.org wrote:
On Mon, Apr 20, 2015 at 03:10:40PM -0700, Ian Wells wrote:
 It would be nice to have a consistent policy here; it would make future
 decision making easier and it would make it easier to write specs if we
 knew what was expected and the possible implementations weren't up for
 (quite so much) debate.  For different reasons, Neutron extensions are also
 not favoured, so there's no clear cut choice to make.

Uhm, there is: https://wiki.openstack.org/wiki/APIChangeGuidelines
and if you read that adding attrs without advertising it (using an
extension, microversion, or whatever) is not an allowed change.

It is also not an unallowed change (given that there's a section that appears 
to define what an unallowed attribute change is).  The page reads very 
awkwardly.

Whatever your preference might be, I think it's best we lose the ambiguity.  
And perhaps advertise that page a little more widely, actually - I hadn't come 
across it in my travels.  And perhaps improve its air of authority: rules on 
this subject should probably live somewhere in a repo so that it's clear 
there's consensus for changes.  Currently anyone can change it for any reason, 
and two years after the last substantive change it's hard to say who even knew 
it was being changed, let alone whether they agreed.

Such a repo exists! [1]

You can see those docs rendered here. [2]

It’s under the purview of the API Working Group. [3] You’re most welcome to 
join us.

That APIChangeGuidelines wiki page really needs to be incorporated into the 
official repo [1]. I’ve added that as an agenda item to our next meeting on 
Thursday 2015-04-23 at 00:00 UTC [4].

[1] http://git.openstack.org/cgit/openstack/api-wg/
[2] http://specs.openstack.org/openstack/api-wg/
[3] https://wiki.openstack.org/wiki/API_Working_Group
[4] https://wiki.openstack.org/wiki/Meetings/API-WG

__
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] [all] [api] gabbi: A tool for declarative testing of APIs

2015-04-21 Thread Everett Toews

On Apr 20, 2015, at 2:45 PM, Chris Dent chd...@redhat.com wrote:

 I wanted to make a quick update on the latest happenings with
 gabbi[0], the tool I've created to do declarative testing of
 OpenStack APIs (starting with Ceilometer and Gnocchi).
 
 * Jay Pipes and I are doing a presentation API Matters at summit.
  The latter of half of that will be me noodling about gabbi,
  including a demo.[1]

This is great! I'm looking forward to attending it.

Miguel and I are doing something similar with our The Good and the Bad of the 
OpenStack REST APIs” presentation [1]. Which is exactly 10 minutes after your 
presentation. :)

Cheers,
Everett

[1] 
https://openstacksummitmay2015vancouver.sched.org/event/6ce758d5c7340db74e0d432e138c6619
__
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] [api] Minor changes to API

2015-04-21 Thread Everett Toews

On Apr 20, 2015, at 2:19 PM, Douglas Mendizabal
douglas.mendiza...@rackspace.commailto:douglas.mendiza...@rackspace.com
wrote:

Hi openstack-dev@

I was wondering if the API Working Group had an opinion on how to deal with
minor changes to the api? For example, what if you wanted to add a new
attribute to a JSON response? I would think that a minor change like that
could be done without having to create a new versioned endpoint. So a newer
release would just add the new attribute without having to create a new /v1.1/
endpoint.

I’d suggest (like others have already) doing microversions like Nova [1].
Creating a new endpoint would be a cruel thing to do to your clients,
especially considering it’s a seemingly backwards compatible change.

However, minor changes like that could still possibly break clients that are
not expecting them. For example, a client that uses the json response as
arguments to a method via **kwargs would start seeing TypeErrors for unexpected
arguments.

And let us not forget statically typed languages. But even there adding a new
attribute isn’t that big of a deal. If there’s an unexpected attribute in a
response, it can simply be ignored. No harm done.

But the user might not even be aware the new attribute is available unless
they’re not looking at their request/response logs. Hence the need for
microversions.

Everett

[1]
http://specs.openstack.org/openstack/nova-specs/specs/kilo/implemented/api-microversions.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] [api] API WG Meeting Time

2015-04-16 Thread Everett Toews

On Apr 1, 2015, at 10:12 AM, Ian Cordasco ian.corda...@rackspace.com wrote:

 
 
 On 4/1/15, 08:24, michael mccune m...@redhat.com wrote:
 
 On 04/01/2015 08:35 AM, Jay Pipes wrote:
 On 03/31/2015 10:13 PM, Everett Toews wrote:
 Ever since daylight savings time it has been increasing difficult for
 many API WG members to make it to the Thursday 00:00 UTC meeting time.
 
 Do we change it so there’s only the Thursday 16:00 UTC meeting time?
 
 On a related note, I can’t make it to tomorrow’s meeting. Can someone
 else please #startmeeting?
 
 We should value our Asian friends' input. I think Having multiple
 meeting times is appropriate. Perhaps not 00:00UTC, but maybe something
 more in their afternoon?
 
 although the 16:00UTC time works well for me, i agree with Jay's
 sentiment here.
 
 +1 for finding another alternating time
 
 Mike
 
 Not just Asia, but Australia and other parts of Europe. I’d like
 Christopher to weigh in since he was the person who had pushed for the
 00:00UTC meeting time.
 
 Is something like 02:00 UTC easier for them?
 
 If no one else volunteers, I’ll #startmeeting the meeting at 00:00UTC this
 week (tonight for the US folks).
 
 —
 Ian

We discussed the time change at yesterday’s API WG meeting on Thursday 00:00 
UTC (only 4 people present) [1]. We didn’t come to any sort of conclusion.

It would be good to hear from those in Asia, Australia, and Europe on the 
subject.

In the absence of consensus, I suppose we’ll leave things the way they are.

Everett

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-04-16-00.00.log.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] [Openstack-operators] [all][log] Openstack HTTP error codes

2015-04-08 Thread Everett Toews

On Jan 29, 2015, at 8:34 PM, Rochelle Grober 
rochelle.gro...@huawei.commailto:rochelle.gro...@huawei.com wrote:

Hi folks!

Changed the tags a bit because this is a discussion for all projects and 
dovetails with logging rationalization/standards/

At the Paris summit, we had a number of session on logging that kept circling 
back to Error Codes.  But, these codes would not be http codes, rather, as 
others have pointed out, codes related to the calling entities and referring 
entities and the actions that happened or didn’t.  Format suggestions were 
gathered from the Operators and from some senior developers.  The Logging 
Working Group is planning to put forth a spec for discussion on formats and 
standards before the Ops mid-cycle meetup.

Working from a Glance proposal on error codes:  
https://review.openstack.org/#/c/127482/ and discussions with operators and 
devs, we have a strawman to propose.  We also have a number of requirements 
from Ops and some Devs.

Here is the basic idea:

Code for logs would have four segments:
Project Vendor/Component  Error Catalog 
number Criticality
Def [A-Z] [A-Z] [A-Z]   -  [{0-9}|{A-Z}][A-Z] - 
[-]-   [0-9]
Ex.  CIN-   NA- 
   0001- 2
Cinder   NetApp 
   driver error no  Criticality
Ex.  GLA-  0A-  
   0051   3
Glance  Api 
error no   Criticality
Three letters for project,  Either a two letter vendor code or a number and 
letter for 0+letter for internal component of project (like API=0A, Controller 
=0C, etc),  four digit error number which could be subsetted for even finer 
granularity, and a criticality number.

This is for logging purposes and tracking down root cause faster for operators, 
but if an error is generated, why can the same codes be used internally for the 
code as externally for the logs?  This also allows for a unique message to be 
associated with the error code that is more descriptive and that can be pre 
translated.  Again, for logging purposes, the error code would not be part of 
the message payload, but part of the headers.  Referrer IDs and other info 
would still be expected in the payload of the message and could include 
instance ids/names, NICs or VIFs, etc.  The message headers is code in Oslo.log 
and when using the Oslo.log library, will be easy to use.

Since this discussion came up, I thought I needed to get this info out to folks 
and advertise that anyone will be able to comment on the spec to drive it to 
agreement.  I will be  advertising it here and on Ops and Product-WG mailing 
lists.  I’d also like to invite anyone who want to participate in discussions 
to join them.  We’ll be starting a bi-weekly or weekly IRC meeting (also 
announced in the stated MLs) in February.

And please realize that other than Oslo.log, the changes to make the errors 
more useable will be almost entirely community created standards with community 
created tools to help enforce them.  None of which exist yet, FYI.

Hi Rocky,

The API WG is trying to come up with a guideline for an error format for the 
HTTP APIs [1]. In that error format is a code field that I was hoping could 
match the code in the logs you mention above.

I noticed in the Logging WG meetings [2] that you mention an Error Code Spec”. 
I’d like to be able to use info from that spec in the example [2] of the error 
format.

Has there been any progress on that spec? Can you link me to it?

Also, if you have time for a review of the error format, I’d like to hear your 
thoughts.

Thanks,
Everett

[1] https://review.openstack.org/#/c/167793/
[2] https://wiki.openstack.org/wiki/Meetings/log-wg
[3] 
https://review.openstack.org/#/c/167793/4/guidelines/errors-example.json,unified


__
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] [api] API WG Meeting Time

2015-03-31 Thread Everett Toews

Ever since daylight savings time it has been increasing difficult for many API 
WG members to make it to the Thursday 00:00 UTC meeting time.

Do we change it so there’s only the Thursday 16:00 UTC meeting time?

On a related note, I can’t make it to tomorrow’s meeting. Can someone else 
please #startmeeting?

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

[openstack-dev] [all] [api] Erring is Caring

2015-03-31 Thread Everett Toews

Hi All,

An API Working Group Guideline for Errors

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

Errors are a crucial part of the developer experience when using an API. As
developers learn the API they inevitably run into errors. The quality and
consistency of the error messages returned to them will play a large part in
how quickly they can learn the API, how they can be more effective with the
API, and how much they enjoy using the API.

We need consistency across all services for the error format returned in the
response body.

The Way Forward

I did a bit of research into the current state of consistency in errors across
OpenStack services [1]. Since no services seem to respond with a top-level
errors key, it's possible that they could just include this key in the
response body along with their usual response and the 2 can live side-by-side
for some deprecation period. Hopefully those services with unstructured errors
should okay with adding some structure. That said, the current error formats
aren't documented anywhere that I've seen so this all feels fair game anyway.

How this would get implemented in code is up to you. It could eventually be
implemented in all projects individually or perhaps a Oslo utility is called
for. However, this discussion is not about the implementation. This discussion
is about the error format.

The Review

I’ve explicitly added all of the API WG and Logging WG CPLs as reviewers to
that patch but feedback from all is welcome. You can find a more readable
version of patch set 4 at [2]. I see the id and “code” fields as the
connection point to what the logging working group is doing.

Thanks,
Everett

[1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Errors
[2]
http://docs-draft.openstack.org/93/167793/4/check/gate-api-wg-docs/e2f5b6e//doc/build/html/guidelines/errors.html

Re: [openstack-dev] [api][nova] Openstack HTTP error codes

2015-03-31 Thread Everett Toews

Top posting to continue the discussion in another thread.

[openstack-dev] [all] [api] Erring is Caring
http://lists.openstack.org/pipermail/openstack-dev/2015-March/060314.html

Everett


On Feb 4, 2015, at 10:29 AM, Duncan Thomas 
duncan.tho...@gmail.commailto:duncan.tho...@gmail.com wrote:

Ideally there would need to be a way to replicate 
errors.openstack.orghttp://errors.openstack.org/ and switch the url, for 
none-internet connected deployments, but TBH sites with that sort of 
requirement are used to weird breakages, so not a huge issue of it can't easily 
be done

On 3 February 2015 at 00:35, Jay Pipes 
jaypi...@gmail.commailto:jaypi...@gmail.com wrote:
On 01/29/2015 12:41 PM, Sean Dague wrote:
Correct. This actually came up at the Nova mid cycle in a side
conversation with Ironic and Neutron folks.

HTTP error codes are not sufficiently granular to describe what happens
when a REST service goes wrong, especially if it goes wrong in a way
that would let the client do something other than blindly try the same
request, or fail.

Having a standard json error payload would be really nice.

{
  fault: ComputeFeatureUnsupportedOnInstanceType,
  messsage: This compute feature is not supported on this kind of
instance type. If you need this feature please use a different instance
type. See your cloud provider for options.
}

That would let us surface more specific errors.
snip

Standardization here from the API WG would be really great.

What about having a separate HTTP header that indicates the OpenStack Error 
Code, along with a generated URI for finding more information about the error?

Something like:

X-OpenStack-Error-Code: 1234
X-OpenStack-Error-Help-URI: http://errors.openstack.org/1234

That way is completely backwards compatible (since we wouldn't be changing 
response payloads) and we could handle i18n entirely via the HTTP help service 
running on errors.openstack.orghttp://errors.openstack.org/.

Best,
-jay


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.org?subject:unsubscribehttp://openstack-dev-requ...@lists.openstack.org/?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



--
Duncan Thomas
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.orgmailto:openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
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] [API] Do we need to specify follow the HTTP RFCs?

2015-03-26 Thread Everett Toews

Top posting the relevant review https://review.openstack.org/#/c/161946/

Everett


On Feb 13, 2015, at 8:44 AM, michael mccune 
m...@redhat.commailto:m...@redhat.com wrote:

On 02/12/2015 02:20 PM, Ryan Brown wrote:
+1 I think the way to go would be:

We suggest (pretty please) that you comply with RFCs 7230-5 and if you
have any questions ask us. Also here are some examples of usage that
is/isn't RFC compliant for clarity


+1, i like the idea of pointing readers towards the RFCs but also providing 
examples.

mike

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: 
openstack-dev-requ...@lists.openstack.orgmailto:openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__
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] [Glance] Experimental API

2015-03-12 Thread Everett Toews

On Mar 12, 2015, at 1:42 PM, Brian Rosmaita brian.rosma...@rackspace.com
wrote:

I don't know how elaborate we want to get here, but Everett Toews had an
interesting suggestion in the openstack-api channel. It would go something
like this:

(1) User gets /x1/search endpoint from service catalog
(2) User does some request against /x1/search

My apologies, I should have been a bit more specific. I actually meant put a
version in some header *instead* of putting any version info in the URL. But I
realize that Glance already uses the /vN/ style in its URLs.

Given the info on header’s below, an /xN/ style would not be necessary.

(3) User receives 400 with an error message like:
This is an experimental API.
You must include the following header with your request:
x-openstack-api-status: acknowledged
By using this header, you acknowledge that while we think this API is
pretty solid, we reserve the right to make breaking changes as we analyze
usage patterns and API consumer comments during the experimental period.
Please send comments to the OpenStack Future Development Mailing List with
the subject [Glance] x1 API.
To subscribe to the mailing list:
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
(4) User makes all subsequent requests including the
x-openstack-api-status header

I don’t think you’d necessarily need to invent a new header. You could reuse
something semantically similar to Nova’s X-OpenStack-Nova-API-Version [1],
which can include an experimental tag.

The experimental nature of the API would need to be documented thoroughly
somewhere. And how to work with it by including the “experimental” tag in the
X-OpenStack-Glance-API-Version header. It would be best if the error message
just linked to that documentation.

Everett

[1]
http://specs.openstack.org/openstack/nova-specs/specs/kilo/approved/api-microversions.html#client-interaction

Re: [openstack-dev] [api][all] - Openstack.error common library

2015-03-03 Thread Everett Toews

On Feb 25, 2015, at 10:47 AM, Doug Hellmann 
d...@doughellmann.commailto:d...@doughellmann.com wrote:

On Wed, Feb 25, 2015, at 09:33 AM, Eugeniya Kudryashova wrote:
Hi, stackers!

As was suggested in topic [1], using an HTTP header was a good solution
for
communicating common/standardized OpenStack API error codes.

So I’d like to begin working on a common library, which will collect all
openstack HTTP API errors, and assign them string error codes. My
suggested
name for library is openstack.error, but please feel free to propose
something different.

The other question is where we should allocate such project, in openstack
or stackforge, or maybe oslo-incubator? I think such project will be too
massive (due to dealing with lots and lots of exceptions)  to allocate it
as a part of oslo, so I propose developing the project on Stackforge and
then eventually have it moved into the openstack/ code namespace when the
other projects begin using the library.

Let me know your feedback, please!

I'm not sure a single library as a home to all of the various error
messages is the right approach. I thought, based on re-reading the
thread you link to, that the idea was to come up with a standard schema
for error payloads and then let the projects fill in the details. We
might need a library for utility functions, but that wouldn't actually
include the error messages.

Did I misunderstand?

Doug

After rereading this thread I came to the same conclusion as Doug did.

There was more support for putting the errors in a standard json error 
payload” as Sean Dague originally suggested. [1]

Regards,
Everett

[1] http://lists.openstack.org/pipermail/openstack-dev/2015-January/055570.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

2015-02-13 Thread Everett Toews

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

On 02/10/2015 08:01 AM, Everett Toews wrote:
On Feb 9, 2015, at 9:28 PM, Jay Pipes 
jaypi...@gmail.commailto:jaypi...@gmail.com
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

[openstack-dev] [api] Missing the next API WG meeting

2015-02-11 Thread Everett Toews

I’ll be missing the next API WG meeting [1] as I’m in some all day training. 
Someone else will have to #startmeeting api wg

Cheers,
Everett

[1] https://wiki.openstack.org/wiki/Meetings/API-WG
__
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

2015-02-10 Thread Everett Toews

On Feb 9, 2015, at 9:28 PM, Jay Pipes 
jaypi...@gmail.commailto: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] Which repo should the API WG use?

2015-02-06 Thread Everett Toews

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

2015-02-03 Thread Everett Toews

On Feb 3, 2015, at 10:07 AM, michael mccune m...@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. 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] [api][nova] Openstack HTTP error codes

2015-02-02 Thread Everett Toews

On Feb 2, 2015, at 7:24 PM, Sean Dague s...@dague.netmailto:s...@dague.net 
wrote:

On 02/02/2015 05:35 PM, Jay Pipes wrote:
On 01/29/2015 12:41 PM, Sean Dague wrote:
Correct. This actually came up at the Nova mid cycle in a side
conversation with Ironic and Neutron folks.

HTTP error codes are not sufficiently granular to describe what happens
when a REST service goes wrong, especially if it goes wrong in a way
that would let the client do something other than blindly try the same
request, or fail.

Having a standard json error payload would be really nice.

{
 fault: ComputeFeatureUnsupportedOnInstanceType,
 messsage: This compute feature is not supported on this kind of
instance type. If you need this feature please use a different instance
type. See your cloud provider for options.
}

That would let us surface more specific errors.
snip

Standardization here from the API WG would be really great.

What about having a separate HTTP header that indicates the OpenStack
Error Code, along with a generated URI for finding more information
about the error?

Something like:

X-OpenStack-Error-Code: 1234
X-OpenStack-Error-Help-URI: http://errors.openstack.org/1234

That way is completely backwards compatible (since we wouldn't be
changing response payloads) and we could handle i18n entirely via the
HTTP help service running on errors.openstack.orghttp://errors.openstack.org.

That could definitely be implemented in the short term, but if we're
talking about API WG long term evolution, I'm not sure why a standard
error payload body wouldn't be better.

Agreed. And using the “X-“ prefix in headers has been deprecated for over 2 
years now [1]. I don’t think we should be using it for new things.

Everett

[1] https://tools.ietf.org/html/rfc6648

__
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] [Openstack-operators] [all][log] Openstack HTTP error codes

2015-01-30 Thread Everett Toews

On Jan 29, 2015, at 7:34 PM, Rochelle Grober 
rochelle.gro...@huawei.commailto:rochelle.gro...@huawei.com wrote:

Hi folks!

Changed the tags a bit because this is a discussion for all projects and 
dovetails with logging rationalization/standards/

At the Paris summit, we had a number of session on logging that kept circling 
back to Error Codes.  But, these codes would not be http codes, rather, as 
others have pointed out, codes related to the calling entities and referring 
entities and the actions that happened or didn’t.  Format suggestions were 
gathered from the Operators and from some senior developers.  The Logging 
Working Group is planning to put forth a spec for discussion on formats and 
standards before the Ops mid-cycle meetup.

Working from a Glance proposal on error codes:  
https://review.openstack.org/#/c/127482/ and discussions with operators and 
devs, we have a strawman to propose.  We also have a number of requirements 
from Ops and some Devs.

Here is the basic idea:

Code for logs would have four segments:
Project Vendor/Component  Error Catalog 
number Criticality
Def [A-Z] [A-Z] [A-Z]   -  [{0-9}|{A-Z}][A-Z] - 
[-]-   [0-9]
Ex.  CIN-   NA- 
   0001- 2
Cinder   NetApp 
   driver error no  Criticality
Ex.  GLA-  0A-  
   0051   3
Glance  Api 
error no   Criticality
Three letters for project,  Either a two letter vendor code or a number and 
letter for 0+letter for internal component of project (like API=0A, Controller 
=0C, etc),  four digit error number which could be subsetted for even finer 
granularity, and a criticality number.

This is for logging purposes and tracking down root cause faster for operators, 
but if an error is generated, why can the same codes be used internally for the 
code as externally for the logs?

I like the idea of the log error codes being aligned with the API errors codes 
but I have some thoughts/concerns.

Project: A client dealing with the API already knows what project (service) 
they’re dealing with. Including this in an API error message would be 
redundant. That’s not necessarily so bad and it could actually be convenient 
for client logging purposes to have this there.

Vendor/Component: Including any vendor information at all would be leaking 
implementation details. This absolutely cannot be exposed in an API error 
message. Even including the component would be leaking too much.

Error Catalog Number: If there could be alignment around this, that would be 
great.

Criticality: This might be useful to clients? I don’t know. I don’t feel too 
strongly about it.

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

[openstack-dev] The API WG mission statement

2015-01-30 Thread 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

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

2015-01-30 Thread Everett Toews

On Jan 30, 2015, at 4:57 PM, Everett Toews everett.to...@rackspace.com 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

Re: [openstack-dev] [api][nova] Openstack HTTP error codes

2015-01-30 Thread Everett Toews


On Jan 29, 2015, at 11:41 AM, Sean Dague s...@dague.net wrote:

 Correct. This actually came up at the Nova mid cycle in a side
 conversation with Ironic and Neutron folks.
 
 HTTP error codes are not sufficiently granular to describe what happens
 when a REST service goes wrong, especially if it goes wrong in a way
 that would let the client do something other than blindly try the same
 request, or fail.
 
 Having a standard json error payload would be really nice.
 
 {
 fault: ComputeFeatureUnsupportedOnInstanceType,
 messsage: This compute feature is not supported on this kind of
 instance type. If you need this feature please use a different instance
 type. See your cloud provider for options.
 }
 
 That would let us surface more specific errors.
 
 Today there is a giant hodgepodge - see:
 
 https://github.com/openstack/tempest-lib/blob/master/tempest_lib/common/rest_client.py#L412-L424
 
 https://github.com/openstack/tempest-lib/blob/master/tempest_lib/common/rest_client.py#L460-L492
 
 Especially blocks like this:
 
if 'cloudServersFault' in resp_body:
message =
 resp_body['cloudServersFault']['message']
elif 'computeFault' in resp_body:
message = resp_body['computeFault']['message']
elif 'error' in resp_body:
message = resp_body['error']['message']
elif 'message' in resp_body:
message = resp_body['message']
 
 Standardization here from the API WG would be really great.

Agreed. I’m 100% for having a guideline for errors. Good error messages is one 
of the most important aspects of a good developer experience for an API. I 
suspect that once you propose an error format for one error, people will 
immediately think of a lot of valid reasons to have a formant for many errors.

I did a bit of research into prior art for error messages. The best discussion 
I found on it starts over in JSON-API [1]. It ultimately results in this error 
format [2]. An example would look like

{
  errors: [
{
  id: some-transaction-id,
  href: https://example.org/more/info/about/this/error.html;,
  code: 0054,
  title: foobar must be in the range [foo, bar)
},
{
  id: ...
}
  ]
}

Do we need to use every field in the format? No.
Can we add additional fields as we see fit? Yes.

We need to do what’s best for OpenStack so I’d like to use a format that’s 
somewhat a standard (at the very least it’s clear that the JSON-API folks have 
done a lot of thinking on it) but that’s flexible enough to meet our 
requirements.

I came across some other error formats such as [3] and [4] but found them to be 
a bit complicated or require things we don’t need.

Thoughts on the JSON-API error format or other formats?

Thanks,
Everett

[1] https://github.com/json-api/json-api/issues/7
[2] http://jsonapi.org/format/#errors
[3] https://github.com/blongden/vnd.error
[4] 
https://google-styleguide.googlecode.com/svn/trunk/jsoncstyleguide.xml#Reserved_Property_Names_in_the_error_object


__
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] 1 or 2 repos for the API WG

2015-01-30 Thread Everett Toews

The suggestion of whether to use 1 or 2 repos for the API WG surfaced on the ML 
here [1]. That thread then morphed into a discussion on whether to use 1 or 2 
repos. I believe it’s correct to say that the consensus on that thread was for 
1 repo.

We also discussed the question of 1 or 2 repos during the API WG meeting [2] 
and, of the 7 attendees that voted, there was unanimous agreement [3] for 1 
repo.

Unless there’s a strong objection or disagreement with my analysis of the 
above, the API WG will move forward and use only 1 repo.

Now the question becomes, which repo?

Everett

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-01-29-16.00.html
[2] http://lists.openstack.org/pipermail/openstack-dev/2015-January/055524.html
[3] 
http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-01-29-16.00.log.html#l-67


__
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] [Openstack-operators] [all][log] Openstack HTTP error codes

2015-01-30 Thread Everett Toews

On Jan 30, 2015, at 3:17 PM, Jesse Keating j...@bluebox.net wrote:

 On 1/30/15 1:08 PM, Everett Toews wrote:
 Project: A client dealing with the API already knows what project
 (service) they’re dealing with. Including this in an API error message
 would be redundant. That’s not necessarily so bad and it could actually
 be convenient for client logging purposes to have this there.
 
 
 Is this really true though? When your interaction with nova is being thwarted 
 by a problem with keystone, wouldn't the end user want to see the keystone 
 name in there as a helpful breadcrumb as to where the problem actually lies?

Once I have the token from Keystone, I’ll be talking directly to the services. 
So either something goes wrong with Keystone and I get no token or I get a 
token and talk directly to a service. Either way a client knows who it's 
talking to.

I suppose one possible case outside of that is token revocation. If I’m talking 
to a service and the token gets revoked, does the error originate in Keystone? 
I’m not really sure.

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] Which repo should the API WG use?

2015-01-30 Thread Everett Toews

It was suggested that the API WG use the openstack-specs [1] and/or the api-wg 
[2] repo to publish its guidelines. We’ve already arrived at the consensus that 
we should only use 1 repo [3]. So the purpose of this thread is to decide...

Should the API WG use the openstack-specs repo or the api-wg repo?

Let’s discuss.

Thanks,
Everett

[1] http://git.openstack.org/cgit/openstack/openstack-specs/
[2] http://git.openstack.org/cgit/openstack/api-wg/
[3] http://lists.openstack.org/pipermail/openstack-dev/2015-January/055687.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] [api] API Definition Formats

2015-01-28 Thread Everett Toews

On Jan 18, 2015, at 9:25 PM, Jay Pipes jaypi...@gmail.com wrote:

 On 01/13/2015 07:41 AM, Sean Dague wrote:
 On 01/09/2015 04:17 PM, Everett Toews wrote:
 One thing that has come up in the past couple of API WG meetings
 [1] is just how useful a proper API definition would be for the
 OpenStack projects.
 
 By API definition I mean a format like Swagger, RAML, API
 Blueprint, etc. These formats are a machine/human readable way of
 describing your API. Ideally they drive the implementation of both
 the service and the client, rather than treating the format like
 documentation where it’s produced as a by product of the
 implementation.
 
 I think this blog post [2] does an excellent job of summarizing the
 role of API definition formats.
 
 Some of the other benefits include validation of
 requests/responses, easier review of API design/changes, more
 consideration given to client design, generating some portion of
 your client code, generating documentation, mock testing, etc.
 
 If you have experience with an API definition format, how has it
 benefitted your prior projects?
 
 Do you think it would benefit your current OpenStack project?
 
 It would hugely benefit OpenStack to have this clear some where that
 was readable.
 
 I don't specifically have experience with these, my only feedback
 would be make sure whatever format supports having multiple examples
 per API call referenced or embedded.
 
 My experience is that API specs aren't typically fully read and
 injested. Instead examples are used to get some minimum working
 code, then bits are spot referenced and evolved until the client code
 looks like it does what was expected. So providing multiple examples
 per API will help more people wrap their head around the interface in
 question.

In my experience developing client tools for OpenStack for the past 2 years, 
the examples are useful but, sooner rather than later, I find myself needing 
the full API definition (I’m avoiding the word spec because it’s overloaded in 
OpenStack land already).

The reason the OpenStack API examples are so useful is because they include 
details that really should be part of the definition. So often I find myself 
looking at an example and wondering where a param came from and its possible 
range of values only to find no mention of that param in the definition.

I’m definitely +1 to multiple examples per API but those examples need to be 
built on top of proper API definitions. I’d like to see us move away from an 
API documentation second mindset to an API definition first mindset. Having the 
API definition drive the implementation of the client and the service.

 This is spot-on, Sean.
 
 I would support making Swagger the API definition format for OpenStack APIs. 
 I think it's by far the best of the bunch, in my experience, and I've used 
 API Blueprint, Swagger, and RAML.
 
 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

[openstack-dev] [api] Next meeting agenda

2015-01-28 Thread Everett Toews

A couple of important topics came up as a result of attending the Cross Project 
Meeting. I’ve added both to the agenda for the next meeting on Thursday 
2015/01/29 at 16:00 UTC.

https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda

The first is the suggestion from ttx to consider using openstack-specs [1] for 
the API guidelines.

The second is what to do about the impact of the guidelines on Swift 
considering it’s API is considerably different than the other OpenStack 
projects [2].

Let’s initially hash this out during the meeting and then bring it back to the 
ML.

Thanks,
Everett

[1] https://github.com/openstack/openstack-specs
[2] https://review.openstack.org/#/c/141229/


__
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] New API guideline accepted for Collection Resources

2015-01-21 Thread Everett Toews

I’d like to announce that a new API guideline has been accepted for Collection 
Resources.

http://specs.openstack.org/openstack/api-wg/guidelines/representation_structure.html#collection-resources

JSON request and response representations for collection resources should be 
an object that includes a top-level property to encapsulate the collection of 
resources. The value of this property should be a JSON array whose elements are 
the JSON representations of the resources in the collection…”

The patch that introduced the API guideline is here

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

If you are creating a new API or a new version of an API, we encourage you to 
follow this guideline for Collection Resources. If you have such a patch coming 
up for review, you can use the APIImpact (as discussed in GitCommitMessages 
[1]) for better discoverability.

Thanks,
Everett

[1] 
https://wiki.openstack.org/wiki/GitCommitMessages#Including_external_references


__
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] [api] Re: [Neutron][L3] Stop agent scheduling without topping sevices

2015-01-21 Thread Everett Toews

On Jan 9, 2015, at 8:15 AM, Jay Pipes jaypi...@gmail.com wrote:

 Adding [api] topic.
 
 On 01/08/2015 07:47 PM, Kevin Benton wrote:
 Is there another openstack service that allows this so we can make the
 API consistent between the two when this change is made?
 
 Kevin, thank you VERY much for asking the above question and caring about 
 consistency in the APIs!
 
 There was a discussion on the ML about this very area of the APIs, and how 
 there is current inconsistency to resolve:
 
 http://openstack-dev.openstack.narkive.com/UbM1J7dH/horizon-all-status-vs-state
 
 You were involved in that thread, so I know you're very familiar with the 
 problem domain :)
 
 In the above thread, I mentioned that this really was something that the API 
 WG should tackle, and this here ML thread should be a catalyst for getting 
 that done.
 
 What we need is a patch proposed to the openstack/api-wg that proposes some 
 guidelines around the REST API structure for disabling some resource for 
 administrative purposes, with some content that discusses the semantic 
 differences between state and status, and makes recommendations on the 
 naming of resource attributes that indicate an admnistrative state.
 
 Of course, this doesn't really address Jack M's question about whether there 
 should be a separate mode (in Jack's terms) to indicate that some resource 
 can be only manually assigned and not automatically assigned. Personally, I 
 don't feel there is a need for another mode. I think if something has been 
 administratively disabled, that an administrator should still be able to 
 manually alter that thing.
 
 All the best,
 -jay

I did some preliminary analysis of the current design on state vs status.

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

So far it doesn’t get into the semantics but identifies which services use 
state and/or status and counts up how many calls use such a param.

Please feel free to add to the analysis.

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

[openstack-dev] [api] API Definition Formats

2015-01-09 Thread Everett Toews

One thing that has come up in the past couple of API WG meetings [1] is just 
how useful a proper API definition would be for the OpenStack projects.

By API definition I mean a format like Swagger, RAML, API Blueprint, etc. These 
formats are a machine/human readable way of describing your API. Ideally they 
drive the implementation of both the service and the client, rather than 
treating the format like documentation where it’s produced as a by product of 
the implementation.

I think this blog post [2] does an excellent job of summarizing the role of API 
definition formats.

Some of the other benefits include validation of requests/responses, easier 
review of API design/changes, more consideration given to client design, 
generating some portion of your client code, generating documentation, mock 
testing, etc. 

If you have experience with an API definition format, how has it benefitted 
your prior projects?

Do you think it would benefit your current OpenStack project?

Thanks,
Everett

[1] https://wiki.openstack.org/wiki/Meetings/API-WG
[2] 
http://apievangelist.com/2014/12/21/making-sure-the-most-important-layers-of-api-space-stay-open/


__
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] [api] [sdk] Proposal to achieve consistency in client side sorting

2015-01-06 Thread Everett Toews

On Jan 6, 2015, at 12:46 PM, Kevin L. Mitchell kevin.mitch...@rackspace.com 
wrote:

 On Tue, 2015-01-06 at 12:19 -0600, Anne Gentle wrote:
 I'm all for consistency. Sounds like a great case for the API Working
 Group to document. You can propose a patch describing the way we want
 sorting to work. 
 
 
 See https://review.openstack.org/#/q/project:openstack/api-wg,n,z
 
 I really think that the API WG should be responsible for the REST API
 only, TBH, and maybe for the Pythonic APIs.  Once we start talking about
 CLI options, I think that's outside the API WG's perview, and we
 probably should have that be up to CLI authors.  My thinking is that a
 REST API and a Python API are both used by developers, where we have one
 set of conventions; but when you start talking about CLI, you're really
 talking about UX, and the rules there can be vastly different.

Agreed. The scope [1] of the API WG is the HTTP (REST) API. 

We won’t be touching any language SDKs (one of which is referred to as Pythonic 
APIs above) or any CLIs.

Thanks,
Everett

[1] https://wiki.openstack.org/wiki/API_Working_Group#Scope
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] Analysis of current API design

2014-12-19 Thread Everett Toews

I thought the analysis on service catalogs might attract some attention. ;)

More inline

On Dec 19, 2014, at 10:17 AM, Amit Gandhi amit.gan...@rackspace.com wrote:

 How do the allocation of the service types in the service catalog get created.

AFAICT it’s arbitrary. Provider picks the string used in the service type.

 For example, looking at the link provided below for service catalogs [1], you 
 have with Rackspace a service type of rax:queues (which is running zaqar).  
 However in devstack, zaqar is listed as “messaging”.  FWIW i think the 
 rackspace entry came before the devstack entry, but there is now an 
 inconsistency.
 
 How do new openstack related projects (that are not incubated/graduated) 
 appear in the service catalog with a consistent service type name that can be 
 used across providers with the confidence it refers to the same set of api's? 
  

That’s what we’re hoping to achieve with guidelines around the service catalog. 
So when the provider goes to pick the strings used in the service catalog, 
there’s consistency.

 Is it just an assumption, or do we need a catalogue somewhere listing what 
 each service type is associated with?  

Yes. This is what would be part of the guideline.

 Does adding it to Devstack pretty much stake claim to the service type?

To date, this has been the case. The DevStack version of the service catalog 
sort of became a de facto standard. But not de facto enough and hence the 
inconsistency.

It’d be great to hear thoughts from Adam Y, Dolph M, and Dean T on the subject. 
I don’t think I have the full picture.

Thanks,
Everett


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

[openstack-dev] [api] Analysis of current API design

2014-12-18 Thread Everett Toews

Hi All,

At the recent API WG meeting [1] we discussed the need for more analysis of 
current API design.

We need to get better at doing analysis of current API design as part of our 
guideline proposals. We are not creating these guidelines in a vacuum. The 
current design should be analyzed and taken into account.

Naturally the type of analysis will vary from guideline to guideline but 
backing your proposals with some kind of analysis will only make them better. 
Let’s take some examples.

1. Anne Gentle and I want to improve the consistency of service catalogs across 
cloud providers both public and private. This is going to require the analysis 
of many providers and we’ve got a start on it here [2]. Hopefully a guideline 
for the service catalog should fall out of the analysis of the many providers.

2. There’s a guideline for metadata up for review [3]. I wasn’t aware of all of 
the places where the concept of metadata is used in OpenStack so I did some 
analysis [4]. I found that the representation was pretty consistent but how 
metadata was CRUDed wasn’t as consistent. I hope that information can help the 
review along.

3. This Guideline for collection resources' representation structures [5] 
basically codifies in a guideline what was found in the analysis. Good stuff 
and it has definitely helped the review along.

For more information about analysis of current API design see #1 of How to 
Contribute [5]

Any thoughts or feedback on the above?

Thanks,
Everett

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2014/api_wg.2014-12-18-16.00.log.html
[2] 
https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Service_Catalog
[3] https://review.openstack.org/#/c/141229/
[4] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Metadata
[5] https://review.openstack.org/#/c/133660/
[6] https://wiki.openstack.org/wiki/API_Working_Group#How_to_Contribute
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [MagnetoDB][api] Hello from the API WG

2014-12-08 Thread Everett Toews

Hello MagnetoDB!

During the latest meeting [1] of the API Working Group (WG) we noticed that 
MagnetoDB made use of the APIImpact flag [2]. That’s excellent and exactly how 
we were hoping the use of flag as a discovery mechanism would work!

We were wondering if the MagentoDB team would like to designate a cross-project 
liaison [3] for the API WG?

We would communicate with that person a bit more closely and figure out how we 
can best help your project. Perhaps they could attend an API WG Meeting [4] to 
get started.

One thing that came up during the meeting was my suggestion that, if MagnetoDB 
had an API definition (like Swagger [5]), we could review the API design 
independently of the source code that implements the API. There are many other 
benefits of an API definition for documentation, testing, validation, and 
client creation. 

Does an API definition exist for the MagnetoDB API or would you be interested 
in creating one?

Either way we’d like to hear your thoughts on the subject.

Cheers,
Everett

P.S. Just to set expectations properly, please note that review of the API by 
the WG does not endorse the project in any way. We’re just trying to help 
design better APIs that are consistent with the rest of the OpenStack APIs.

[1] 
http://eavesdrop.openstack.org/meetings/api_wg/2014/api_wg.2014-12-04-16.01.html
[2] https://review.openstack.org/#/c/138059/
[3] https://wiki.openstack.org/wiki/CrossProjectLiaisons#API_Working_Group
[4] https://wiki.openstack.org/wiki/Meetings/API-WG
[5] http://swagger.io/


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

Re: [openstack-dev] [api] Counting resources

2014-11-26 Thread Everett Toews

On Nov 20, 2014, at 4:06 PM, Eoghan Glynn 
egl...@redhat.commailto:egl...@redhat.com wrote:

How about allowing the caller to specify what level of detail
they require via the Accept header?

▶ GET /prefix/resource_name
 Accept: application/json; detail=concise

The Accept request-header field can be used to specify certain media types 
which are acceptable for the response.” [1]

detail=concise is not a media type and looking at the grammar in the RFC it 
wouldn’t be valid. It’s not appropriate for the Accept header.

Everett

[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1

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

Re: [openstack-dev] [api] APIImpact flag for specs

2014-11-24 Thread Everett Toews

I’ve also added APIImpact flag info to the Git Commit Messages page [1].

Everett

[1]
https://wiki.openstack.org/wiki/GitCommitMessages#Including_external_references

On Nov 19, 2014, at 5:23 PM, Everett Toews
everett.to...@rackspace.commailto:everett.to...@rackspace.com wrote:

On Nov 13, 2014, at 2:06 PM, Everett Toews
everett.to...@rackspace.commailto:everett.to...@rackspace.com wrote:

On Nov 12, 2014, at 10:45 PM, Angus Salkeld
asalk...@mirantis.commailto:asalk...@mirantis.com wrote:

On Sat, Nov 1, 2014 at 6:45 AM, Everett Toews
everett.to...@rackspace.commailto:everett.to...@rackspace.com wrote:
Hi All,

Chris Yeoh started the use of an APIImpact flag in commit messages for specs in
Nova. It adds a requirement for an APIImpact flag in the commit message for a
proposed spec if it proposes changes to the REST API. This will make it much
easier for people such as the API Working Group who want to review API changes
across OpenStack to find and review proposed API changes.

For example, specifications with the APIImpact flag can be found with the
following query:

https://review.openstack.org/#/q/status:open+project:openstack/nova-specs+message:apiimpact,n,z

Chris also proposed a similar change to many other projects and I did the rest.
Here’s the complete list if you’d like to review them.

Barbican: https://review.openstack.org/131617
Ceilometer: https://review.openstack.org/131618
Cinder: https://review.openstack.org/131620
Designate: https://review.openstack.org/131621
Glance: https://review.openstack.org/131622
Heat: https://review.openstack.org/132338
Ironic: https://review.openstack.org/132340
Keystone: https://review.openstack.org/132303
Neutron: https://review.openstack.org/131623
Nova: https://review.openstack.org/#/c/129757
Sahara: https://review.openstack.org/132341
Swift: https://review.openstack.org/132342
Trove: https://review.openstack.org/132346
Zaqar: https://review.openstack.org/132348

There are even more projects in stackforge that could use a similar change. If
you know of a project in stackforge that would benefit from using an APIImapct
flag in its specs, please propose the change and let us know here.

I seem to have missed this, I'll place my review comment here too.

I like the general idea of getting more consistent/better API. But, is
reviewing every spec across all projects just going to introduce a new non
scalable bottle neck into our work flow (given the increasing move away from
this approach: moving functional tests to projects, getting projects to do more
of their own docs, etc..). Wouldn't a better approach be to have an API liaison
in each project that can keep track of new guidelines and catch potential
problems?

I see have added a new section here:
https://wiki.openstack.org/wiki/CrossProjectLiaisons

Isn't that enough?

I replied in the review. We’ll continue the discussion there.

The cross project liaisons are big help but the APIImpact flag let’s the API WG
automate discovery of API changing specs. It's just one more tool in the box to
help us find changes that impact the API.

Note that the patch says nothing about requiring a review from someone
associated with the API WG. If you add the APIImpact flag and nobody comes
along to review it, continue on as normal.

The API WG is not intended to be a gatekeeper of every change to every API. As
you say that doesn't scale. We don't want to be a bottleneck. However, tools
such as the APIImpact flag can help us be more effective.

(Angus suggested I give my review comment a bit more visibility. I agree :)

Everett

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

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

Re: [openstack-dev] [api] API-WG meeting (note time change this week)

2014-11-19 Thread Everett Toews

On Nov 19, 2014, at 4:56 AM, Christopher Yeoh cbky...@gmail.com wrote:

 Hi,
 
 We have moved to alternating times each week for the API WG meeting so
 people from other timezones can attend. Since this is an odd week 
 the meeting will be Thursday UTC 1600. Details here:
 
 https://wiki.openstack.org/wiki/Meetings/API-WG
 
 The google ical feed hasn't been updated yet, but thats not surprising
 since the wiki page was only updated a few hours ago.

I see on the Meetings [1] page the link to the Google Calendar iCal feed.

1. Do you know the link to the Google Calendar itself, not just the iCal feed?

2. Do you know if there is a way to subscribe to only the API WG meeting from 
that calendar?

Thanks,
Everett


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

Re: [openstack-dev] [api] Cross-Project Liaison for the API Working Group

2014-11-19 Thread Everett Toews

On Nov 16, 2014, at 4:59 PM, Christopher Yeoh cbky...@gmail.com wrote:

 My 2c is we should say The liason should be the PTL or whomever they 
 delegate to be their representative  and not mention anything about the 
 person needing to be a core developer. It removes any ambiguity about who 
 ultimately decides who the liason is (the PTL) without saying that they have 
 to do the work themselves.

Sure. Go ahead and change it to that.

Everett


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

Re: [openstack-dev] [api] Summit summary

2014-11-19 Thread Everett Toews

Does anybody know what happened to the Etherpad? It’s completely blank now!!!

If you check the Timeslider, it appears that it only ever existed on Nov. 15. 
Bizarre.

Everett


On Nov 14, 2014, at 5:05 PM, Everett Toews everett.to...@rackspace.com wrote:

 Hi All,
 
 Here’s a summary of what happened at the Summit from the API Working Group 
 perspective.
 
 Etherpad: https://etherpad.openstack.org/p/kilo-crossproject-api-wg
 
 The 2 design summit sessions on Tuesday were very well attended, maybe 100ish 
 people I’m guessing. I got the impression there were developers from a 
 diverse set of projects just from the people who spoke up during the session. 
 We spent pretty much all of these 2 sessions discussing the working group 
 itself.
 
 Some action items of note:
 
 Update the wiki page [1] with the decisions made during the discussion
 Add an additional meeting time [2] to accommodate EU time
 Email the WG about the Nova (and Neutron?) API microversions effort and how 
 it might be a strategy for moving forward with API changes
 
 Review the rest of the action items in the etherpad to get a better picture.
 
 The follow up session on Thursday (last slot of the day) was attended by 
 about half the people of the Tuesday sessions. We reviewed what happened on 
 Tuesday and then got to work. We ran through the workflow of creating a 
 guideline. We basically did #1 and #2 of How to Contribute [3] but instead of 
 first taking notes on the API Improvement in the wiki we just discussed it in 
 the session. We then submitted the patch for a new guideline [4].
 
 As you can see there’s still a lot of work to be done in that review. It may 
 even be that we need a fresh start with it. But it was a good exercise for 
 everyone present to walk through the process together for the first time. I 
 think it really helped put everyone on the same page for working together as 
 a group.
 
 Thanks,
 Everett
 
 [1] https://wiki.openstack.org/wiki/API_Working_Group
 [2] https://wiki.openstack.org/wiki/Meetings/API-WG
 [3] https://wiki.openstack.org/wiki/API_Working_Group#How_to_Contribute
 [4] https://review.openstack.org/#/c/133087/
 
 
 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


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