Identity API and Versioning

[Jon Perritt]

I'm wondering if would be make sense to refactor the OpenStack Identity code to be more in line with the OpenStack Compute code format (namely, hierarchical). Looking at the docs, the format could be similar.

Those same docs also bring up a question of versioning. It looks like there are currently 2 versions (v2 and v3) of that API. How do we plan to handle concurrent and potentially conflicting API versions? Maybe (potentially temporarily) have a different subdirectory under 'identity' for each version and determine an end-of-life point for the older version.

Thoughts?

-- JRP

[Samuel Falvo II]

On Thu, Apr 3, 2014 at 10:46 PM, Jon Perritt <jrpe...@gmail.com> wrote:
> I'm wondering if would be make sense to refactor the OpenStack Identity code
> to be more in line with the OpenStack Compute code format (namely,
> hierarchical). Looking at the docs, the format could be similar.

The Identity API was the prototype to which I adhered when writing the
compute code (it was the first of the 0.2.0 APIs to be rewritten as a
proof of concept), so I feel that they are already in the same style
as each other. Can you point out where you find disagreement of
coding style/format?

> Those same docs also bring up a question of versioning. It looks like there
> are currently 2 versions (v2 and v3) of that API. How do we plan to handle
> concurrent and potentially conflicting API versions? Maybe (potentially
> temporarily) have a different subdirectory under 'identity' for each version
> and determine an end-of-life point for the older version.

My current plans were to introduce new subdirectories, e.g., identity
(for 2.0) vs identity3 (for 3.0). Not quite sure how to handle 3.0 vs
3.1, etc. though.

--
Samuel A. Falvo II

[Jon Perritt]

On Sun, Apr 6, 2014 at 6:44 PM, Samuel Falvo II <sam....@gmail.com> wrote:

On Thu, Apr 3, 2014 at 10:46 PM, Jon Perritt <jrpe...@gmail.com> wrote:
> I'm wondering if would be make sense to refactor the OpenStack Identity code
> to be more in line with the OpenStack Compute code format (namely,
> hierarchical). Looking at the docs, the format could be similar.

The Identity API was the prototype to which I adhered when writing the
compute code (it was the first of the 0.2.0 APIs to be rewritten as a
proof of concept), so I feel that they are already in the same style
as each other.  Can you point out where you find disagreement of
coding style/format?

Sure. For example, having a directory structure similar to that of the OpenStack Identity API website. Namely, something like

gophercloud

  - openstack

    - identity

      - tokens

      - servicecatalog

      - endpoints

      - users

      - groups

      - ...

    - compute

    - storage

  - rackspace

and then within tokens, users, groups, etc there would be functions that define Create, Get, Update, Delete, etc. Then, when writing code, it would look something like the following:

import "github.com/rackspace/gophercloud/openstack/servicecatalog"

catalog, err := servicecatalog.Get(servicecatalog.GetOpts{

        Name: "serviceId-here",

})

cr, err := servicecatalog.List(servicecatalog.ListOpts{

})

catalogs := servicecatalog.GetServices(cr)

Also, perhaps moving tests to acceptance/openstack/identity_test.go. I see some of them there now, but also some in the openstack/identity directory.

These are purely musings/suggestions. The thinking is that consistency in the API across products will increase the ease of use of the library.

 

> Those same docs also bring up a question of versioning. It looks like there
> are currently 2 versions (v2 and v3) of that API. How do we plan to handle
> concurrent and potentially conflicting API versions? Maybe (potentially
> temporarily) have a different subdirectory under 'identity' for each version
> and determine an end-of-life point for the older version.

My current plans were to introduce new subdirectories, e.g., identity
(for 2.0) vs identity3 (for 3.0).  Not quite sure how to handle 3.0 vs
3.1, etc. though.

I agree. We may want to consider having a directory structure like the following:

openstack

  - identity

    - v2

    - v3

  - compute

  - storage

If OpenStack follows semantic versioning, shouldn't we be able to add code to, say, v3 if they release v3.1 without having to worry about backwards compatibility?

[Samuel Falvo II]

On Mon, Apr 7, 2014 at 1:40 PM, Jon Perritt <jrpe...@gmail.com> wrote:
> and then within tokens, users, groups, etc there would be functions that
> define Create, Get, Update, Delete, etc. Then, when writing code, it would
> look something like the following:
>
> import "github.com/rackspace/gophercloud/openstack/servicecatalog"
>
> catalog, err := servicecatalog.Get(servicecatalog.GetOpts{
> Name: "serviceId-here",
> })
>
> cr, err := servicecatalog.List(servicecatalog.ListOpts{
>
> })
>
> catalogs := servicecatalog.GetServices(cr)

This seems like a reasonable idea; however, authentication is a bit of
a special case. We get a service catalog as part of a tokens
operation, which has the side-effect of authentication as well. Then
we need a way to somehow support automatic re-authentication for those
users who don't care to manually check token expiry all the time.
We'd need to take these into consideration if we're to re-arrange the
identity SDK.

> openstack
> - identity
> - v2
> - v3
> - compute
> - storage

I'm going to oppose this idea on the basis that we'll have a plurality
of v2 and v3 modules, and no meaningful way to identify which is which
by static inspection of the code. Or, you'll end up with the equally
unidiomatic:

import (
identity ".../identity/v2"
compute ".../compute/v2"
)

On the other hand, that doesn't look all that bad. Not too happy with
the stuttering that's required, but if that's what we need to do...

I've thought of using .../v2/{identity,compute,...}, but this has some
problems that other people objected to, including difficulty of
finding related components when they're strewn about the filesystem.

[Jon Perritt]

This seems like a reasonable idea; however, authentication is a bit of
a special case.  We get a service catalog as part of a tokens
operation, which has the side-effect of authentication as well.  

For version 2, quite right. Version 3 breaks out service catalog and tokens separately.

 

Then we need a way to somehow support automatic re-authentication for those
users who don't care to manually check token expiry all the time.
We'd need to take these into consideration if we're to re-arrange the
identity SDK.

 If I have some time next week, I'll do some feasibility testing on this. While I do think it would be more consistent, the current implementation has "currently working" on its side  :) 

I'm going to oppose this idea on the basis that we'll have a plurality
of v2 and v3 modules, and no meaningful way to identify which is which
by static inspection of the code.  Or, you'll end up with the equally
unidiomatic:

import (
    identity ".../identity/v2"
    compute ".../compute/v2"
)

On the other hand, that doesn't look all that bad.  Not too happy with
the stuttering that's required, but if that's what we need to do...

I've thought of using .../v2/{identity,compute,...}, but this has some
problems that other people objected to, including difficulty of
finding related components when they're strewn about the filesystem.

Given the two options, I'd prefer the former (nesting the version within the service) for the reason you mentioned. Ultimately, though, it's not terribly inconvenient either way; I do think that we should decide before rolling out v0.2.0 so that anybody wanting to use that version won't have to change all their import statements later on.

[Samuel Falvo II]

On Thu, Apr 10, 2014 at 4:00 PM, Jon Perritt <jrpe...@gmail.com> wrote:
> For version 2, quite right. Version 3 breaks out service catalog and tokens
> separately.

Oh, that's interesting.

> If I have some time next week, I'll do some feasibility testing on this.
> While I do think it would be more consistent, the current implementation has
> "currently working" on its side :)

I actually had a plan of attack for this, but never got around to
implementing it yet. It's a requirement for 0.2.0 release though.

> Given the two options, I'd prefer the former (nesting the version within the

Yep, I have to agree. I picked up a copy of the book "Programming in
Go", and in the back, there is a section which deals with versioning
that arrives at the same conclusion. So, I think, especially in the
absence of further feedback on this list, that we should go the route
of import foo ".../foo/Vn".