[Starlingx-discuss] API requests: stx-config

[Arce Moreno, Abraham]

stx-config team,

Based in some time spent now within stx-config and with the objective to align
our REST API Documentation with our REST APIs, 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 ]

The mismatch between documentation [0] and information via API Query is addressed
under [3] and [4].

  ? Heads Up! The description includes the word "interfaces" however as you will find
    below, "interfaces is also listed in the documentation but not intuitively found as
    a REST method under the API query output. More information below.

[ v1/ ]

Here we are showing 3 different views of what we are seeing within stx-config
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 REST METHODs below to include,
we are adding in the second column what it seems to be the match for the valid
API REST methods:

  System                                                   > isystems
  Clusters                                                 > clusters
  Interfaces                                             > ?
  Partitions                                              > ! /v1/ihosts/​{host_id}​/partitions || /v1/partitions/​{partition_id}​
  Volume Groups                                   > ! /v1/ihosts/​{host_id}​/ilvgs || /v1/ilvgs/​{volumegroup_id}​
  Physical Volumes                                > ! /v1/ihosts/​{host_id}​/ipvs || /v1/ipvs/​{physicalvolume_id}​
  Ceph Storage Functions                     > ! /v1/ihosts/​{host_id}​/istors || /v1/istors/​{stor_id}​
  Profiles                                                  > iprofile
  DNS                                                        > idns
  NTP                                                        > intp
  External OAM                                      > iextoam
  Infrastructure Subnet                        > iinfra
  DRBD Configuration                           > drbdconfig
  SNMP Communities                           > icommunity
  SNMP Trap Destinations                   > itrapdest
  Devices                                                 > ! /v1/devices/​{device_id}​ || /v1/ihosts/​{host_id}​/pci_devices
  Service Parameter                              > service_parameter
  SDN Controllers                                  > sdn_controller
  Remote Logging                                  > remotelogging
  Networks                                             > networks
  Address Pools                                     > addrpools
  Addresses                                            > addresses
  Routes                                                  > ! /v1/ihosts/​{host_id}​/routes
  Storage Backends                               > storage_backend
  Storage Tiers                                       > ! storage_tiers
  Controller Filesystem                        > controller_fs
  Ceph Monitors                                   > ceph_mon
  System Certificate Configuration    > ! certificate
  Custom Firewall Rules                      > firewallrules

  ? Are all the names and API REST methods correctly matched?
  ? Are all the valid API REST method names correct?
  ? "Interfaces" is listed under v1/ API Version output [2]
     as an expected service but a REST METHOD match was not found, are we talking
     about "Interface" one of the following ones:
     1) Is it the "interface_networks" REST method?
     2) Or found under "Profiles" as described under its description:
          "...This includes interface profiles..."
     3) Or found under "SDN Controllers" as described under its description:
         "...SDN manager interface..."
     4) Or as simple as "Networks" interfaces?

[ v1/ ] [ Current Official API Documentation ]

The following API REST methods documented under [0] give valid API output:

  - System
  - Clusters
  - DNS
  - NTP
  - External OAM
  - Infrastructure Subnet
  - DRBD Configuration
  - SNMP Communities
  - SNMP Trap Destinations
  - Service Parameter
  - SDN Controllers
  - Remote Logging
  - Networks
  - Address Pools
  - Storage Backends
  - Storage Tiers
  - Controller Filesystem
  - Ceph Monitors
  - System Certificate Configuration
  - Custom Firewall Rules
  - Partitions
  - Volume Groups
  - Physical Volumes
  - Ceph Storage Functions
  - Devices
  - Addresses
  - Routes

The following API REST method documented under [0] has an invalid name:

  - Profiles   Documentation pointing to: /v1/iprofiles
                     and a valid v1/ endpoint:  http://10.10.10.2:6385/v1/iprofile

  ? Is this a valid Documentation change from "iprofiles" to "iprofile"?

[ v1/ ] [ API Query Output ]

Based in our "[Starlingx-discuss] API requests: stx-ha" [3] we learned the following
API REST methods from "System Inventory API v1" are assigned to stx-ha:

  - services
  - servicenodes
  - service_groups

And in our "[Starlingx-discuss] API requests: stx-metal" [4] the following are assigned
to stx-metal:

- lldp_neighbours
- ihosts
- icpu
- lldp_agents

And now these API REST methods are assigned to stx-config:

  - isystems
  - clusters
  - <Interfaces>
  - ! /v1/ihosts/​{host_id}​/partitions || /v1/partitions/​{partition_id}​
  - ! /v1/ihosts/​{host_id}​/ilvgs || /v1/ilvgs/​{volumegroup_id}​
  - ! /v1/ihosts/​{host_id}​/ipvs || /v1/ipvs/​{physicalvolume_id}​
  - ! /v1/ihosts/​{host_id}​/istors || /v1/istors/​{stor_id}​
  - iprofile
  - idns
  - intp
  - iextoam
  - iinfra
  - drbdconfig
  - icommunity
  - itrapdest
  - ! /v1/devices/​{device_id}​ || /v1/ihosts/​{host_id}​/pci_devices
  - service_parameter
  - sdn_controller
  - remotelogging
  - networks
  - addrpools
  - addresses
  - ! /v1/ihosts/​{host_id}​/routes
  - storage_backend
  - ! storage_tiers
  - controller_fs
  - ceph_mon
  - ! certificate
  - firewallrules

Leaving the following assigned to other StarlingX components, more to come once we review
the remaining StarlingX projects:

  - links
  - storage_file
  - storage_lvm
  - interface_networks
  - id
  - ptp
  - media_types
  - upgrade
  - imemory
  - storage_ceph_external
  - health
  - license
  - storage_ceph
  - storage_external
  - iuser
  - helm_charts
  - inode
  
  ? 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?
  ? Is there anything we need to take care of?

Thanks for your initial support.

[0] https://docs.starlingx.io/api-ref/stx-config/index.html
[1] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis
[2] https://docs.starlingx.io/api-ref/stx-config/api-ref-sysinv-v1-config.html?expanded=shows-details-for-configuration-api-v1-detail#api-versions
[3]http://lists.starlingx.io/pipermail/starlingx-discuss/2018-November/001868.html
[4] http://lists.starlingx.io/pipermail/starlingx-discuss/2018-November/002032.html