Open Stack

On 11/16/2016 10:22 AM, Valeriy Ponomaryov wrote:
> For the moment Manila project, as well as Cinder, does have
> inconsistency between entity and API naming, such as:
> - "share type" ("volume type" in Cinder) entity has "/types/{id}" URL
> - "share snapshot" ("volume snapshot" in Cinder) entity has
> "/snapshots/{id}" URL
>
> BUT, Manila has other Manila-specific APIs as following:
>
> - "share network" entity and "/share-networks/{id}" API
> - "share server" entity and "/share-servers/{id}" API
>
> And with implementation of new features [1] it becomes a problem,
> because we start having
> "types" and "snapshots" for different things (share and share groups,
> share types and share group types).
>
> So, here is first open question:
>
> What is our convention in naming APIs according to entity names?
>
> - Should APIs contain full name or it may be shortened?
> - Should we restrict it to some of the variants (full or shortened) or
> allow some API follow one approach and some follow other approach,
> consider it as "don't care"? Where "don't care" case is current
> approach, de facto.

I think that consistency is important but the question is consistency 
with what. Right now we have an inconsistent design and it will be 
effort to change it either way. If we're going to spend that effort 
there needs to be a good reason.

Initially I had been in favor of "share-groups" over just "groups", 
however if we go that direction it will make all of the places where we 
don't use the share- prefix that much more glaring. Consistency with the 
the past and with cinder would suggest that we should avoid using share- 
prefixes everywhere possible, and we should look into removing them from 
places where we added them somewhat gratuitously (share networks, share 
servers, share instances).

> Then, we have second question here:
>
> - Should we use only "dash" ( - ) symbols in API names or "underscore" (
> _ ) is allowed?

Underscores should never be used. This seems like a mistake when 
instances were added.

> - Should we allow both variants at once for each API?

Thanks to microversions, if we change any API we can support only the 
old name for the old microversion and only the new name for the new 
microversion. There is no reason to support both at the same time for 
any microversion

> - Should we allow APIs use any of variants and have zoo with various
> approaches?
>
> In Manila project, mostly "dash" is used, except one API -
> "share_instances".
>
> [1] https://review.openstack.org/#/c/315730/
>
> --
> Kind Regards
> Valeriy Ponomaryov
> vponomaryov at mirantis.com <mailto:vponomaryov at mirantis.com>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>