[openstack-dev] [API] Upgrading to API WG Recommendations

Ian Cordasco ian.cordasco at RACKSPACE.COM
Thu Jan 15 01:40:49 UTC 2015

Hey all,

In the last meeting of the working group, we discussed what the goals of
the group are and how those affect existing projects and new ones. In
particular, some people seem confused as to whether the group’s goal is to
create recommendations for ideal APIs or to document the existing APIs and
choose the best practices from those. This is still somewhat up for
debate, but most want to shoot for the stars while being willing to

Keep in mind, right now nothing committed to openstack/api-wg is a set in
stone. Most of the reviews that are currently in progress are undergoing
heavy discussion both on gerrit and in meetings.

The point was brought up that some recommendations that the working group
forms will be jarring for APIs to implement when going from vN.* to vN+1.0
for both developers and consumers. Client libraries often provide
compatibility (or upgrade-path) versions to help bridge the gap between
going from vN.* to vN+1.0. As a group, we’re looking for feedback from the
developers on the following topics:

- Does this seem preferable?
- Does it sound reasonable and maintainable?
- Does it seem reasonable as a way of improving user experience and

If you have a positive feeling for this idea, there are a couple

- Should the API WG recommend a strategy for this versioning path?
- If so, should the versioning path work like:

  - vN.M -> vN.99 -> vN+1.0
    We would use .99 to indicate that you it’s compatible with vN.* but
also provides information/endpoints in vN+1)
  - or vN.M -> vN+1.0 -> vN+2.0
    In this case we would make N+1 be the compatibility version (perhaps
do not allow increments of the minor version) and N+2 would be the version
of the API that is fully in-compliance with the Working Group’s final

Thanks in advance for your feedback,

More information about the OpenStack-dev mailing list