Re: [openstack-dev] [manila][cinder] [api] API and entity naming consistency
On 11/17/2016 04:03 AM, Ravi, Goutham wrote: > > > 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. 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 <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 an
Re: [openstack-dev] [manila][cinder] [api] API and entity naming consistency
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 pr
Re: [openstack-dev] [manila][cinder] [api] API and entity naming consistency
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.
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
Re: [openstack-dev] [manila][cinder] [api] API and entity naming consistency
+ [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.
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
