[Starlingx-discuss] API requests: stx-fault

[Arce Moreno, Abraham]

stx-fault team,

Based in some time spent within stx-fault and with the objective to align our
REST API Documentation [0] 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 ]

When we look at the name and description reported out by
    curl -i http://10.10.10.2:18002/
there is a mismatch between documentation [1] and information via API Query:

API Documentation:

    Name: stx-fault API
    Description: StarlingX Fault 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: Fault Management API
    Description: Fault Management is an OpenStack project which provides REST API services
    for alarms and logs.

  ? 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 [2]
- 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:18002/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 endpoint name:

  Alarms             > alarms
  Event Log          > event_log
  Event Suppression  > event_suppression

  ? Are all the names and API nodes correctly matched?

>From this same output, "links" has a reference to:
  "http://www.windriver.com/developer/fm/dev/api-spec-v1.html"

  ? Does his reference needs to change to:
    https://docs.starlingx.io/api-ref/stx-fault/index.html

[ v1/ ] [ Current Official API Documentation ]

Current Official API documentation [3] includes the following 3 REST API methods
under "API Versions" v1/ details:

- Alarms:             http://10.10.10.2:6385/v1/alarms
- Event Log:          http://10.10.10.2:6385/v1/event_log
- Event Suppression:  http://10.10.10.2:6385/v1/event_suppression

[ v1/ ] [ API Query Output ]

API queries output shows these API REST methods:

- alarms
- event_log
- event_suppression

  ? Do we need another level of review?
  ? Is there anything we need to take care of?

Thanks for your initial support.

[0] https://docs.starlingx.io/api-ref/stx-fault/
[1] https://docs.starlingx.io/api-ref/stx-fault/api-ref-fm-v1-fault.html?expanded=lists-information-about-fault-management-api-versions-detail#api-versions
[2] https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis
[3] https://docs.starlingx.io/api-ref/stx-fault/api-ref-fm-v1-fault.html?expanded=lists-information-about-fault-management-api-versions-detail,shows-details-for-fault-management-api-v1-detail#api-versions