Open Stack

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.

    > > 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