<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:0 0 0 0 0 0 0 0 0 0;}
@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.apple-tab-span
        {mso-style-name:apple-tab-span;}
span.EmailStyle18
        {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:1934700135;
        mso-list-type:hybrid;
        mso-list-template-ids:-2083744776 1554284380 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;
        text-indent:-.25in;
        font-family:"Times New Roman";
        mso-fareast-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;
        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;
        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;
        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;
        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;
        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;
        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;
        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;
        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;color:red">See in-lined comments below,<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:Calibri;color:red">Greg.<o:p></o:p></span></p>
<p class="MsoNormal" style="margin-left:.5in"><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" style="margin-left:.5in"><b><span style="font-family:Calibri;color:black">From:
</span></b><span style="font-family:Calibri;color:black">"Arce Moreno, Abraham" <abraham.arce.moreno@intel.com><br>
<b>Date: </b>Friday, August 3, 2018 at 12:39 PM<br>
<b>To: </b>"starlingx-discuss@lists.starlingx.io" <starlingx-discuss@lists.starlingx.io><br>
<b>Subject: </b>[Starlingx-discuss] StarlingX API Documentation<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">A new goal in collaboration with our Tech Writing team is to document StarlingX APIs,
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">so we did an initial research on what it means for StarlingX so your feedback is<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">highly appreciated.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><span class="apple-tab-span">           
</span><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[ OpenStack :: API ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">For this activity we are initially be considering from API Documentation 2 separate<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">efforts for each project:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - API Guide .. the concepts in the API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - API Ref .. a reference for the API<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Can we prioritize one over the other?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:red">[Greg]<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">The concepts in our APIs are pretty standard ... so I would prioritize the API Reference work higher.<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[ StarlingX :: API ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">It seems we can categorize the StarlingX APIs in 2:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - Brand New APIs from StarlingX projects<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - Existing APIs from OpenStack projects<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal"><span style="color:red">[Greg]<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">Actually what we currently do ( <a href="https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc">
https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc</a> ) is<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-.25in;mso-list:l0 level1 lfo1"><![if !supportLists]><span style="color:red"><span style="mso-list:Ignore">-<span style="font:7.0pt "Times New Roman"">         
</span></span></span><![endif]><span style="color:red">Fully document New / StarlingX –specific APIs  (i.e. sysinv APIs), and<o:p></o:p></span></p>
<p class="MsoListParagraph" style="text-indent:-.25in;mso-list:l0 level1 lfo1"><![if !supportLists]><span style="color:red"><span style="mso-list:Ignore">-<span style="font:7.0pt "Times New Roman"">         
</span></span></span><![endif]><span style="color:red">Document ONLY (non-upstreamed) extensions to existing OpenStack APIs<o:p></o:p></span></p>
<p class="MsoListParagraph" style="margin-left:1.0in;text-indent:-.25in;mso-list:l0 level2 lfo1">
<![if !supportLists]><span style="font-family:"Courier New";color:red"><span style="mso-list:Ignore">o<span style="font:7.0pt "Times New Roman"">  
</span></span></span><![endif]><span style="color:red">i.e. we did NOT want to duplicate documentation for existing OpenStack APIs<o:p></o:p></span></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[ StarlingX :: API :: Brand New ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">The projects falling into this category are the following:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - [0] NFVI Orchestration<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - [1] High Availability/Process Monitoring/Service Management<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - [2] StarlingX System Configuration Management<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - [3] Horizon plugins for new StarlingX services<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  - [4] Installation/Update/Patching/Backup/Restore<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Can we considered all the above to be included in this API documentation effort?
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Are we missing any other?<o:p></o:p></p>
<p class="MsoNormal"><span style="color:red">[Greg]<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">Yeah basically we would organize it based on the re-partitioned areas of sysinv ....<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">Actually initially grouped by any new API Endpoints we are introducing due to the sysinv re-partitioning, and<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">Secondly grouped by functional areas.<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[ StarlingX :: API :: Existing ]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">All projects living under our starlingx-staging github organization [5] with<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">upstream contributions [6] e.g. horizon, ceilometer, etc.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">We have not gone through a deeper review if we are modifying/adding<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">new calls into the OpenStack projects however if we are and we need to document<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">them:<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">- There is official OpenStack <Project> API documentation, we can make references
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  to them for the existing calls<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">- What about the modifications/additions? Should we document them?
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  What is the best place for this? We were talking in our weekly call about stx-docs<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">  is a good place for things without a repo, is this a good example?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">- Any easy way besides "find + grep" to get where those API modifications are happening?<o:p></o:p></p>
<p class="MsoNormal"><span style="color:red">[Greg]<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">As mentioned ... our previous strategy has been to have a separate document chapter that describes<br>
ONLY the extensions that we have done to existing OpenStack APIs.  With the intent being that we<br>
did NOT want to duplicate existing OpenStack API documentation<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[ StarlingX :: API :: Unit Tests]<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">OpenStack projects includes Unit Tests. Is this something we also need to consider<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">for our StarlingX Bran New APIs?<o:p></o:p></p>
<p class="MsoNormal"><span style="color:red">[Greg]<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red">Not sure what you’re suggesting here ... Unit Tests for our APIs ?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="color:red"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="color:red">Greg.<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[0] <a href="http://git.openstack.org/cgit/openstack/stx-nfv/">
http://git.openstack.org/cgit/openstack/stx-nfv/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[1] <a href="http://git.openstack.org/cgit/openstack/stx-ha/">
http://git.openstack.org/cgit/openstack/stx-ha/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[2] <a href="http://git.openstack.org/cgit/openstack/stx-config/">
http://git.openstack.org/cgit/openstack/stx-config/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[3] <a href="http://git.openstack.org/cgit/openstack/stx-gui/">
http://git.openstack.org/cgit/openstack/stx-gui/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[4] <a href="http://git.openstack.org/cgit/openstack/stx-update/">
http://git.openstack.org/cgit/openstack/stx-update/</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[5] <a href="https://github.com/starlingx-staging">
https://github.com/starlingx-staging</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">[6] <a href="http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack">
http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">_______________________________________________<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Starlingx-discuss mailing list<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><a href="mailto:Starlingx-discuss@lists.starlingx.io">Starlingx-discuss@lists.starlingx.io</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><a href="http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss">http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss</a><o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
</div>
</body>
</html>