Hi everyone,<div><br /></div><div>The docs team still needs this feedback, can someone from stx-metal help us to fill the gaps?</div><div><br /></div><div>Thanks in advance!</div><div><br /><br />--<br />Sent from Yandex.Mail for mobile<br /><br />28.11.2018, 14:24, "Arce Moreno, Abraham" <abraham.arce.moreno@intel.com>:<br /><blockquote type="cite"><p>stx-metal team,<br /><br />As a result of time spent within stx-metal, we have some initial questions<br />with respect to documentation and source code so we are kindly requesting your<br />comments for questions "?" under each section [ Section ] [Sub Section]<br /><br />Please assume:<br /><br />- The require X-Auth-Token is in place to authenticate, only URLs might be shown.<br />- StarlingX is configured as Standard Controller: 2 Controllers, 2 Computes.<br /><br />[ Project Information ]<br /><br />When we look at the name and description reported out by<br />    curl -i <a href="http://10.10.10.2:6385/">http://10.10.10.2:6385/</a><br />there is a mismatch between documentation [0] and information via API Query:<br /><br />API Documentation:<br /><br />    Name: StarlingX SysInv API<br />    Description: StarlingX System API allows for the management of physical servers. <br />    This includes inventory collection and configuration of hosts, ports, interfaces, CPUs,<br />    disk, memory, and system configuration.<br />    The API also supports the configuration of the cloud's SNMP interface. <br /><br />Source Code via API Query:<br /><br />    Name: Titanium SysInv API<br />    Description: Titanium Cloud System API allows for the management of physical servers.<br />    This includes inventory collection and configuration of hosts, ports, interfaces, CPUs,<br />    disk, memory, and system configuration.<br />    The API also supports alarms and fault collection for the cloud itself as well as the<br />    configuration of the cloud's SNMP interface.<br /><br />? Can you please let us know where the modifications are required? API Documentation<br />  or Source Code?<br /><br />[ v1/ ]<br /><br />Here we are showing 3 different views of what we are seeing within stx-metal<br />project:<br /><br />- Our initial "Migration WADL to RST", see history here [1]<br />- What we have documented in our "Current Official API Documentation" pages [0]<br />- What the "API Query Output" is actually showing with<br />  curl -i <a href="http://10.10.10.2:6385/v1/..">http://10.10.10.2:6385/v1/..</a>.<br /><br />[ v1/ ] [ Migration WADL to RST ]<br /><br />Migration analysis from WADL to RST format gave us the endpoints below to include,<br />we are adding in the second column what it seems to be the match for the valid<br />API endpoint name:<br /><br />    Hosts                   > ihosts<br />    Ports                    > ports<br />    CPUs                    > icpu<br />    Memory              > imemorys<br />    Disks                    > idisks<br />    SensorGroup     > isensorgroups<br />    Sensor                 > isensors<br />    LLDP Agents       > lldp_agents<br />    LLDP Neighbors > lldp_neighbours<br /><br /> ? Are all the names and API nodes correctly matched?<br /> ? Are all the valid API node names correct? E.g. imemorys Vs imemories<br /><br />[ v1/ ] [ Current Official API Documentation ]<br /><br />Current Official API documentation [0] includes the following 5 endpoints<br />under "API Versions" v1/ details:<br /><br />- LLDP Neighbors: <a href="http://10.10.10.2:6385/v1/lldp_neighbours/">http://10.10.10.2:6385/v1/lldp_neighbours/</a><br />- Hosts:                   <a href="http://10.10.10.2:6385/v1/ihosts/">http://10.10.10.2:6385/v1/ihosts/</a><br />- CPUs:                    <a href="http://10.10.10.2:6385/v1/icpu/">http://10.10.10.2:6385/v1/icpu/</a><br />- LLDP Agents:       <a href="http://10.10.10.2:6385/v1/lldp_agents/">http://10.10.10.2:6385/v1/lldp_agents/</a><br />- Ports:                    <a href="http://10.10.10.2:6385/v1/iports/">http://10.10.10.2:6385/v1/iports/</a><br /><br />  ? All of them are valid endpoints except for:<br />    - icpu is not found, the correct working endpoint is:<br />      <a href="http://10.10.10.2:6385/v1/icpus/">http://10.10.10.2:6385/v1/icpus/</a><br />    - iports is not found, the correct working endpoint is:<br />      <a href="http://10.10.10.2:6385/v1/ports/">http://10.10.10.2:6385/v1/ports/</a><br />    Any objection to make the documentation change?<br /><br />The following 3 endpoints are not shown under "API Versions" v1/ details but they<br />have a valid top level v1/ endpoint:<br /><br />- Memory           Documentation pointing to: /v1/ihosts/{host_id}/imemorys<br />                             and a valid top level v1/ endpoint:  <a href="http://10.10.10.2:6385/v1/imemorys/">http://10.10.10.2:6385/v1/imemorys/</a><br />- SensorGroup  Documentation pointing to: /v1/ihosts/{host_id}/isensorgroups<br />                             and a valid top level v1/ endpoint:  <a href="http://10.10.10.2:6385/v1/isensorgroups/">http://10.10.10.2:6385/v1/isensorgroups/</a><br />- Sensor              Documentation pointing to: /v1/ihosts/{host_id}/isensors<br />                             and a valid top level v1/ endpoint:  <a href="http://10.10.10.2:6385/v1/isensors/">http://10.10.10.2:6385/v1/isensors/</a><br /><br />  ? Since they a valid top level v1/ endpoint, do we need to add them under our<br />    "API Versions" v1/ details documentation [2]?<br /><br />idisks does not have a valid v1/ endpoint, it is accessed only through v1/ihosts:<br /><br />- Disks          > <a href="http://10.10.10.2:6385/v1/ihosts/">http://10.10.10.2:6385/v1/ihosts/</a>{host_id}/idisks/<br /><br />  ? It seems ok, anything to add here? anything to modify?<br /><br />[ v1/ ] [ API Query Output ]<br /><br />API queries output shows these endpoints:<br /><br />- lldp_neighbours<br />- ihosts<br />- icpu<br />- lldp_agents<br /><br />Plus additional ones, some other are assigned to other StarlingX repos:<br /><br />- firewallrules<br />- addresses<br />- links<br />- remotelogging<br />- ceph_mon<br />- itrapdest<br />- iextoam<br />- intp<br />- storage_file<br />- storage_lvm<br />- interface_networks<br />- inode<br />- id<br />- ptp<br />- media_types<br />- servicegroup<br />- upgrade<br />- imemory<br />- networks<br />- storage_ceph_external<br />- health<br />- clusters<br />- drbdconfig<br />- icommunity<br />- helm_charts<br />- iprofile<br />- servicenodes<br />- iinfra<br />- storage_backend<br />- controller_fs<br />- services<br />- sdn_controller<br />- addrpools<br />- license<br />- service_parameter<br />- storage_ceph<br />- idns<br />- isystems<br />- storage_external<br />- iuser<br /><br />Important!<br /><br />Focusing on endpoints related to stx-metal, let's take a look at this<br />v1/ API Query Output and choose "imemory":<br /><br />    "imemory": [<br />        {<br />            "href": "<a href="http://10.10.10.2:6385/v1/imemory/">http://10.10.10.2:6385/v1/imemory/</a>",<br />            "rel": "self"<br />        },<br />        {<br />            "href": "<a href="http://10.10.10.2:6385/imemory/">http://10.10.10.2:6385/imemory/</a>",<br />            "rel": "bookmark"<br />        }<br />    ],<br /><br />When we query "imemory" endpoint based in the information presented above,<br />we find this endpoint as not valid, knowing from previous procedures the<br />endpoint name "imemorys" is the valid one.<br /><br />  ? Do we need another level of review?<br />  ? Should we target an update to the documentation in terms of number<br />    of services we are documenting comparing the 3 perspectives?<br /><br />[ v1/ihosts ]<br /><br />Some fields might be different. API Documentation does not include the field "tboot"<br />but our API query shows this "tboot" field under each host:<br /><br />    "tboot": "false",<br /><br />  ? Is this different since it could have been queried in a AIO Vs a our Controller Storage?<br /><br />In general:<br /><br />  ? Is there any need to go deeper into reviewing the content fo the rest of the endpoints outputs?<br />    We understand this might be a job for the API testing @ Zuul so let us know how can we help from<br />    the documentation perspective.<br />  ? Anything else to add? mention? required?<br /><br />Thanks for your initial support.<br /><br />[0] <a href="https://docs.starlingx.io/api-ref/stx-metal/">https://docs.starlingx.io/api-ref/stx-metal/</a><br />[1] <a href="https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis">https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis</a><br />[2] <a href="https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#api-versions">https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#api-versions</a><br />[3] <a href="https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#memory">https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#memory</a><br />_______________________________________________<br />Starlingx-discuss mailing list<br /><a href="mailto:Starlingx-discuss@lists.starlingx.io">Starlingx-discuss@lists.starlingx.io</a><br /><a href="http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss">http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss</a><br /></p></blockquote></div>