<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Title" content="">
<meta name="Keywords" content="">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Courier New";
panose-1:2 7 3 9 2 2 5 2 4 4;}
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0in;
margin-right:0in;
margin-bottom:0in;
margin-left:.5in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:Calibri;
color:windowtext;}
span.msoIns
{mso-style-type:export-only;
mso-style-name:"";
text-decoration:underline;
color:teal;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:1746217468;
mso-list-type:hybrid;
mso-list-template-ids:1489144514 -1997927066 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;}
@list l0:level1
{mso-level-start-at:0;
mso-level-number-format:bullet;
mso-level-text:-;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:20.25pt;
text-indent:-.25in;
font-family:Calibri;
mso-fareast-font-family:Calibri;
mso-bidi-font-family:"Times New Roman";}
@list l0:level2
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:56.25pt;
text-indent:-.25in;
font-family:"Courier New";}
@list l0:level3
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:92.25pt;
text-indent:-.25in;
font-family:Wingdings;}
@list l0:level4
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:128.25pt;
text-indent:-.25in;
font-family:Symbol;}
@list l0:level5
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:164.25pt;
text-indent:-.25in;
font-family:"Courier New";}
@list l0:level6
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:200.25pt;
text-indent:-.25in;
font-family:Wingdings;}
@list l0:level7
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:236.25pt;
text-indent:-.25in;
font-family:Symbol;}
@list l0:level8
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:272.25pt;
text-indent:-.25in;
font-family:"Courier New";}
@list l0:level9
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:none;
mso-level-number-position:left;
margin-left:308.25pt;
text-indent:-.25in;
font-family:Wingdings;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
--></style>
</head>
<body bgcolor="white" lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">+ [api] in the subject to attract API-WG attention.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">We already have a guideline in the API-WG around resource names for “_” vs “-“ -
<a href="https://specs.openstack.org/openstack/api-wg/guidelines/naming.html#rest-api-resource-names">
https://specs.openstack.org/openstack/api-wg/guidelines/naming.html#rest-api-resource-names</a> . With some exceptions (like share_instances that you mention), I see that we have implemented – across other resources.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">Body elements however, we prefer underscores, i.e, do not have body elements that follow CamelCase or mixedCase.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">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:<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:20.25pt;text-indent:-.25in;mso-list:l0 level1 lfo1">
<![if !supportLists]><span style="font-size:11.0pt;font-family:Calibri"><span style="mso-list:Ignore">-<span style="font:7.0pt "Times New Roman"">
</span></span></span><![endif]><span style="font-size:11.0pt;font-family:Calibri">Get the endpoint from the catalog for the specific version of the service API I want<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:20.25pt;text-indent:-.25in;mso-list:l0 level1 lfo1">
<![if !supportLists]><span style="font-size:11.0pt;font-family:Calibri"><span style="mso-list:Ignore">-<span style="font:7.0pt "Times New Roman"">
</span></span></span><![endif]><span style="font-size:11.0pt;font-family:Calibri">Append resource to endpoint and make my REST calls.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">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
<a href="https://review.openstack.org/#/c/386555/)">https://review.openstack.org/#/c/386555/)</a> . However, there is a mountain of a difference between the underlying intent of /share-networks and neutron’s /networks resources.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">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.
<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">--<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri">Goutham<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri"><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-family:Calibri;color:black">From: </span>
</b><span style="font-family:Calibri;color:black">Valeriy Ponomaryov <vponomaryov@mirantis.com><br>
<b>Reply-To: </b>"OpenStack Development Mailing List (not for usage questions)" <openstack-dev@lists.openstack.org><br>
<b>Date: </b>Wednesday, November 16, 2016 at 4:22 PM<br>
<b>To: </b>"OpenStack Development Mailing List (not for usage questions)" <openstack-dev@lists.openstack.org><br>
<b>Subject: </b>[openstack-dev] [manila][cinder] API and entity naming consistency<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<div>
<p class="MsoNormal">For the moment Manila project, as well as Cinder, does have inconsistency between entity and API naming, such as:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- "share type" ("volume type" in Cinder) entity has "/types/{id}" URL<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- "share snapshot" ("volume snapshot" in Cinder) entity has "/snapshots/{id}" URL<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">BUT, Manila has other Manila-specific APIs as following:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">- "share network" entity and "/share-networks/{id}" API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- "share server" entity and "/share-servers/{id}" API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">And with implementation of new features [1] it becomes a problem, because we start having<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">"types" and "snapshots" for different things (share and share groups, share types and share group types).<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">So, here is first open question:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">What is our convention in naming APIs according to entity names?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">- Should APIs contain full name or it may be shortened?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- 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.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">Then, we have second question here:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">- Should we use only "dash" ( - ) symbols in API names or "underscore" ( _ ) is allowed?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- Should we allow both variants at once for each API?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal">- Should we allow APIs use any of variants and have zoo with various approaches?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">In Manila project, mostly "dash" is used, except one API - "share_instances".<o:p></o:p></p>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal">[1] <a href="https://review.openstack.org/#/c/315730/">https://review.openstack.org/#/c/315730/</a><o:p></o:p></p>
</div>
<div>
<div>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<p class="MsoNormal">-- <o:p></o:p></p>
<div>
<div>
<p class="MsoNormal">Kind Regards<br>
Valeriy Ponomaryov<br>
<a href="mailto:vponomaryov@mirantis.com" target="_blank">vponomaryov@mirantis.com</a><o:p></o:p></p>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>