Open Stack

On 11/17/2016 04:03 AM, Ravi, Goutham wrote:
> 
> 
> On>  11/16/16, 8:22 PM, "Ben Swartzlander" <ben at swartzlander.org> wrote:
> 
>     > > On 11/16/2016 11:28 AM, Ravi, Goutham wrote:
>     > > + [api] in the subject to attract API-WG attention.
>     > >
>     > >
>     > >
>     > > We already have a guideline in the API-WG around resource names for “_”
>     > > vs “-“ -
>     > > https://specs.openstack.org/openstack/api-wg/guidelines/naming.html#rest-api-resource-names
>     > > . With some exceptions (like share_instances that you mention), I see
>     > > that we have implemented – across other resources.
>     > >
>     > > Body elements however, we prefer underscores, i.e, do not have body
>     > > elements that follow CamelCase or mixedCase.
>     > >
>     > >
>     > >
>     > > My personal preference would be to retain “share-” in the resource
>     > > names. As an application developer that has to integrate with block
>     > > storage and shared file systems APIs, I would like the distinction if
>     > > possible; because at the end of the day, the typical workflow for me
>     > > would be:
>     > >
>     > > -          Get the endpoint from the catalog for the specific version of
>     > > the service API I want
>     > >
>     > > -          Append resource to endpoint and make my REST calls.
>     > >
>     > >
>     > >
>     > > The distinction in the APIs would ensure my code is readable. It would
>     > > be interesting to see what the API working group prefers around this. We
>     > > have in the past realized that /capabilities could to be uniform across
>     > > services because it is expected to spew a bunch of strings to the user
>     > > (warning: still under contention, see
>     > > https://review.openstack.org/#/c/386555/) . However, there is a mountain
>     > > of a difference between the underlying intent of /share-networks and
>     > > neutron’s /networks resources.
>     > 
>     > So you'd be in favor of renaming cinder's /snapshots URL to 
>     > /volume-snapshots and manila's /snapshots URL to /share-snapshots?
>     > 
>     > I agree the explicitness is appealing, but we have to recognize that the 
>     > existing API has tons of implicitness in the names, and changing the 
>     > existing API will cause pain no matter how well-intentioned the changes are.
>     > 
> 
> 
>     No, I’m not in favor of renaming existing resources. I support the explicitness
>     in some if not all manila resources, share-networks, share-metadata, share-servers,
>     share-replicas. Renaming snapshots to /share-snapshots won’t fetch us much but
>     frustration. To Valeiry’s original question, I support /share-groups and /share-group-types
>     over /groups or /types. The roughly equivalent cinder resources are /groups and 
>    /group_types.

Agree.  And I wish that on the cinder review I had asked if there might
ever be any other types of groups needed in cinder than volume groups,
the way I did in the manila review for /share-groups rather than just
/groups.

-- Tom


> 
>     > > However, whatever we decide there, let’s not overload resources within
>     > > the project, an explicit API will be appreciated for application
>     > > development. share-types and group-types are not ‘types’ unless
>     > > everything about these resources (i.e, database representation) are the
>     > > same and all HTTP verbs that you are planning to add correspond to both.
>     > >
>     > >
>     > >
>     > > --
>     > >
>     > > Goutham
>     > >
>     > >
>     > >
>     > > *From: *Valeriy Ponomaryov <vponomaryov at mirantis.com>
>     > > *Reply-To: *"OpenStack Development Mailing List (not for usage
>     > > questions)" <openstack-dev at lists.openstack.org>
>     > > *Date: *Wednesday, November 16, 2016 at 4:22 PM
>     > > *To: *"OpenStack Development Mailing List (not for usage questions)"
>     > > <openstack-dev at lists.openstack.org>
>     > > *Subject: *[openstack-dev] [manila][cinder] API and entity naming
>     > > consistency
>     > >
>     > >
>     > >
>     > > 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.
>     > >
>     > >
>     > >
>     > > Then, we have second question here:
>     > >
>     > >
>     > >
>     > > - Should we use only "dash" ( - ) symbols in API names or "underscore" (
>     > > _ ) is allowed?
>     > >
>     > > - Should we allow both variants at once for each API?
>     > >
>     > > - 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
>     > >
>     
>     
>     __________________________________________________________________________
>     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
>     
> 
> 
> __________________________________________________________________________
> 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
>