[Starlingx-discuss] API requests: stx-metal

[Arce Moreno, Abraham]

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#Analysis
[2] 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
[3] https://docs.starlingx.io/api-ref/stx-metal/api-ref-sysinv-v1-metal.html?expanded=shows-details-for-bare-metal-api-v1-detail#memory