On> 11/16/16, 8:22 PM, "Ben Swartzlander" <b...@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 <vponomar...@mirantis.com>
> > *Reply-To: *"OpenStack Development Mailing List (not for usage
> > questions)" <openstack-dev@lists.openstack.org>
> > *Date: *Wednesday, November 16, 2016 at 4:22 PM
> > *To: *"OpenStack Development Mailing List (not for usage questions)"
> > <openstack-dev@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
> > vponomar...@mirantis.com <mailto:vponomar...@mirantis.com>
> >
> >
> >
> >
__________________________________________________________________________
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
openstack-dev-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
