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