[openstack-dev] [Nova] V3 API Review Checklist and style guide

Christopher Yeoh cbkyeoh at gmail.com
Sat Nov 23 12:21:22 UTC 2013

On Fri, 22 Nov 2013 11:41:16 +0000
John Garbutt <john at johngarbutt.com> wrote:
> On 19 November 2013 11:40, Christopher Yeoh <cbkyeoh at gmail.com> wrote:
> > I've updated the Nova review check list with some details for
> > reviewing V3 API changesets and started a bit of a style guide for
> > the API.
> >
> > Checklist:
> > https://wiki.openstack.org/w/index.php?title=ReviewChecklist#Nova_Review_Checklist
> Looks good, but should we mention what we can change after Icehouse,
> when we bump the extension version.
> Obviously, that detail should also go in the docs.

Ah yes that adds yet another dimension to the production of api docs
which I hadn't considered :-( I hope we don't need to version our api
samples, but we might have to unless the docs only show the interface
for the most recent version of an extension.

> I wonder if we should rename all the core extensions to start with
> "os-" for consistency?
> Makes it easier to expand/contact what is in "core" at a later date
> without changing the API format.

That's a very good question. So to recap, we currently only use the os-
prefix for non core extensions. This follows on from the convention
established in the V2 API which was mostly followed well.

Making both non core and core extensions start with the os- prefix would
make it a lot easier to expand/contract what is in "core" at a later
date with a lot less churn. However that does sort of call into question
exactly what sort of stability guarantees we are going to be giving to
the v3 API.

Stepping back a bit, the definition of the core API in Nova will
presumably flow up to branding around Openstack and will represent
part of the compatibility between different Openstack clouds. When
people move between them, they can be assured that the core Nova API
will always be present, whilst the extensions present may vary.

But if we ever move stuff into our out of core, that breaks that
assurance as a core API on one Openstack cloud may not be present on
another. So once the V3 API is frozen will we ever be able to move
anything into or out of core without an API version bump?

> > Style Guide: https://wiki.openstack.org/wiki/Nova/APIStyleGuide
> Awesome. Only thing I see missing is a list of the error codes we use,
> and how we use them.

Ok. I'll add something on that.


More information about the OpenStack-dev mailing list