Jump to: navigation, search

Difference between revisions of "StarlingX/Developer Guide/API Documentation"

(Starling API SysInv)
(Tracking)
 
(41 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== Intro ==
 
== Intro ==
  
StarlingX team is working in collaboration with Tech Writing team to document StarlingX APIs, this page reflects the research on what it means for StarlingX. <br>
+
[[StarlingX/Docs_and_Infra]] is working in collaboration with Tech Writers team to document StarlingX APIs, this page reflects the research on what it means for StarlingX.
See Story [https://storyboard.openstack.org/#!/story/2002712 Doc Provide StarlingX API documentation]
+
<br>
 +
* Storyboard [https://storyboard.openstack.org/#!/story/2002712 Doc Provide StarlingX API documentation]
  
 
== Analysis ==
 
== Analysis ==
Line 8: Line 9:
 
Adding information from Greg Waines who has done some research related to this:
 
Adding information from Greg Waines who has done some research related to this:
  
=== Objective ===
+
=== Tracking ===
  
 
Provide upstream API Documentation for the individual StarlingX sub-projects:
 
Provide upstream API Documentation for the individual StarlingX sub-projects:
  
* Host Management (stx-metal)
 
 
* Configuration Management (stx-config)
 
* Configuration Management (stx-config)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 26515 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/603258/ Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605254/ stx-config: API ref doc content added]
 +
** Gerrit Review [https://review.openstack.org/#/c/609172 Add api-ref and relnotes publish jobs]
 +
** Gerrit Review [https://review.openstack.org/#/c/609544 Another test of api-ref and releasenotes publish jobs]
 +
* Software Management (stx-distcloud)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 26621 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/604482/ Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605107/ stx-distcloud: API ref doc content added]
 +
* Fault Management (stx-fault)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 26697 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/604946 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605259/ stx-fault: API ref doc content added]
 
* Service Management (stx-ha)
 
* Service Management (stx-ha)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 25749 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/599466 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605272/ stx-ha: API ref doc content added]
 +
* Host Management (stx-metal)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 24451 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/590097 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605275/ stx-metal: API ref doc content added]
 +
* Infrastructure Orchestration (stx-nfv)
 +
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 26671 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/604852 Doc: OpenStack API Reference Guide]
 +
** Gerrit Review [https://review.openstack.org/#/c/605233/ stx-nfv: API ref doc content added]
 
* Software Management (stx-update)
 
* Software Management (stx-update)
* Infrastructure Orchestration (stx-nfv)
+
** Storyboard Task [https://storyboard.openstack.org/#!/story/2002712 26659 Doc: OpenStack API Reference Guide]
* Fault Management (stx-fault)
+
** Gerrit Review [https://review.openstack.org/#/c/604841/ Doc: OpenStack API Reference Guide]
 
+
** Gerrit Review [https://review.openstack.org/#/c/605278/ stx-update: API ref doc content added]
 +
* StarlingX Documentation (stx-docs)
 +
** Gerrit Review [https://review.openstack.org/#/c/605277/ stx-docs: API ref doc content added for remaining 4 docs]
 +
<br>
 
The existing API documentation for SYSINV is managed in a very very old mechanism, using maven and wadl files, circa Grizzly.
 
The existing API documentation for SYSINV is managed in a very very old mechanism, using maven and wadl files, circa Grizzly.
  
Line 28: Line 55:
  
 
* Dcmanager API v1 (Tbd)
 
* Dcmanager API v1 (Tbd)
 +
** Move to starlingx-staging/stx-distcloud
 
* NFV VIM API v1 (NFV VIM Service REST API)
 
* NFV VIM API v1 (NFV VIM Service REST API)
 +
** Move to stx-nfv
 
* Patching API v1 (Patching REST API)
 
* Patching API v1 (Patching REST API)
 +
** Move to stx-update
 
* System Inventory API v1 (System Inventory (SysInv) REST API)
 
* System Inventory API v1 (System Inventory (SysInv) REST API)
 +
** Map to stx-metal
 +
*** 6.4. Hosts
 +
*** 6.5. Ports
 +
*** 6.7. CPUs
 +
*** 6.8. Memory
 +
*** 6.11. Disks
 +
*** 6.9. SensorGroup
 +
*** 6.10. Sensor
 +
*** 6.26. LLDP Agents
 +
*** 6.27. LLDP Neighbors
 +
** Map to stx-config
 +
*** 6.2. System
 +
*** 6.3. Clusters
 +
*** 6.6 Interfaces
 +
*** 6.12. Partitions
 +
*** 6.14. Volume Groups
 +
*** 6.15. Physical Volumes
 +
*** 6.13. Ceph Storage Functions
 +
*** 6.16. Profiles
 +
*** 6.17. DNS
 +
*** 6.18. NTP
 +
*** 6.19. External OAM
 +
*** 6.20. Infrastructure Subnet
 +
*** 6.21. DRBD Configuration
 +
*** 6.22. SNMP Communities
 +
*** 6.23. SNMP Trap Destinations
 +
*** 6.24. Devices
 +
*** 6.25. Service Parameter
 +
*** 6.31. SDN Controllers
 +
*** 6.32. Remote Logging
 +
*** 6.33. Networks
 +
*** 6.34. Address Pools
 +
*** 6.35. Addresses
 +
*** 6.36. Routes
 +
*** 6.37. Storage Backends
 +
*** 6.38. Storage Tiers
 +
*** 6.39. Controller Filesystem
 +
*** 6.40. Ceph Monitors
 +
*** 6.44. System Certificate Configuration
 +
*** 6.45. Custom Firewall Rules
 +
** Map to stx-fault
 +
*** 11.2 Alarms
 +
*** 11.3 Event Log
 +
*** 11.4 Event Suppression
 +
** Map to stx-ha
 +
*** 10.2 Services
 +
*** 10.3 Service Nodes
 +
*** 10.4 Service Groups
 +
** Map to stx-update
 +
*** 6.41. System Health
 +
*** 6.42. Software Loads
 +
*** 6.43. Software Upgrade
 +
** DELETE
 +
*** 6.46. License
 
* Block Storage V2 Extensions API (Extensions to Block Storage REST API)
 
* Block Storage V2 Extensions API (Extensions to Block Storage REST API)
 +
** Move to starlingx-staging/stx-python-cinderclient
 
* Compute V2 Extensions API (Extensions to Compute REST API)
 
* Compute V2 Extensions API (Extensions to Compute REST API)
 +
** Move to starlingx-staging/stx-nova
 
* Image V2 Extensions API (Extensions to Image REST API)
 
* Image V2 Extensions API (Extensions to Image REST API)
 +
** Move to starlingx-staging/stx-glance
 
* Networking V2 Extensions API (Extensions to Networking REST API)
 
* Networking V2 Extensions API (Extensions to Networking REST API)
 +
** Move to starlingx-staging/stx-neutron
 
* Telemetry V2 Extensions API (Extensions to Telemetry REST API)
 
* Telemetry V2 Extensions API (Extensions to Telemetry REST API)
 +
** No longer exists ... we've removed these changes in last couple of months.
 
<br>
 
<br>
 
There are no Extensions to Identity REST API (Keystone) and Orchestration REST API (Heat).
 
There are no Extensions to Identity REST API (Keystone) and Orchestration REST API (Heat).
Line 41: Line 130:
 
=== Work Items ===
 
=== Work Items ===
  
* create ./api-ref/source directory under each StarlingX sub-project for containing API Documentation
+
* [https://storyboard.openstack.org/#!/story/2002712 Storyboard Task 24440: OpenStack API Service Implementation]
* convert the appropriate sections of existing SYSINV API Documentation from maven/wadl to .rst/.yaml format
+
** Create ./api-ref/source directory under each StarlingX sub-project for containing API Documentation
* update the sub-project's (or StarlingX's) tox.ini file to include a configuration for building the API reference locally
+
** Update the sub-project's (or StarlingX's) tox.ini file to include a configuration for building the API reference locally
* Add the api-ref-jobs template to StarlingX project, patch the zuul.d/projects.yaml file stored in openstack-infra/project-config repository.
+
* [https://storyboard.openstack.org/#!/story/2002712 Storyboard Task 24441: StarlingX API Documentation Migration]
* Add links to StarlingX sub-project's API DOCs from the API landing page and the OpenStack Governance reference document, projects.yaml.
+
** Convert the appropriate sections of existing SYSINV API Documentation from maven/wadl to .rst/.yaml format
* To add a link to the StarlingX sub-project’s API docs to the API landing page, patch the index.rst file stored in the openstack/api-site repository.
+
* [https://storyboard.openstack.org/#!/story/2002712 Storyboard Task 24443:  OpenStack API Reference Pages Creation  ]
* To ensure the openstack/governance repository has the correct link to your API documentation, patch the reference/projects.yaml file in the openstack/governance repository.
+
** Add the api-ref-jobs template to StarlingX project, patch the zuul.d/projects.yaml file stored in openstack-infra/project-config repository.
 +
* [https://storyboard.openstack.org/#!/story/2002712 Storyboard Task: To Be Defined]
 +
** Add links to StarlingX sub-project's API DOCs from the API landing page and the OpenStack Governance reference document, projects.yaml.
 +
** To add a link to the StarlingX sub-project’s API docs to the API landing page, patch the index.rst file stored in the openstack/api-site repository.
 +
** To ensure the openstack/governance repository has the correct link to your API documentation, patch the reference/projects.yaml file in the openstack/governance repository.
  
 
=== Acceptance Criteria ===
 
=== Acceptance Criteria ===
Line 93: Line 186:
 
You can use the content as a starting point. However, the mechanism used is outdated using maven and wadl files.  So you need to use the more current approach.
 
You can use the content as a starting point. However, the mechanism used is outdated using maven and wadl files.  So you need to use the more current approach.
  
Greg Waines did some research on this.
+
Greg Waines did some research on this [[https://wiki.openstack.org/wiki/StarlingX/Developer_Guide/API_Documentation#Analysis Here]]
 
 
<source lang="sh">
 
[user@0756d97288e1 starlingx]$ repo grep mvn.repo.tgz
 
cgcs-root/stx/stx-integ/restapi-doc/centos/build_srpm.data:          $CGCS_BASE/downloads/mvn.repo.tgz \
 
cgcs-root/stx/stx-integ/restapi-doc/centos/restapi-doc.spec:Source1: mvn.repo.tgz
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile:      if [ ! -e mvn.repo.tgz ]; then  \
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile:      tar -xvzf ./mvn.repo.tgz -C ./mvn.repo/
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/Makefile.cache: cd mvn.repo && tar -czvf ../mvn.repo.tgz . && cd ..
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:Steps to produce mvn.repo.tgz [Maven cache]
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:mock -r $MY_BUILD_CFG_STD --copyout /builddir/build/BUILD/restapi-doc-1.6.0/mvn.repo.tgz ~/
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:cp ~/mvn.repo.tgz $MY_REPO/stx/downloads/
 
cgcs-root/stx/stx-integ/restapi-doc/restapi-doc/README.mvn_cache:# ln -s ../../../downloads/mvn.repo.tgz mvn.repo.tgz
 
stx-tools/centos-mirror-tools/tarball-dl.lst:!mvn.repo.tgz#mvn#https://repo.maven.apache.org/maven2
 
stx-tools/centos-mirror-tools/tarball-dl.sh:        # The mvn.repo.tgz tarball will be created downloading a serie of
 
stx-tools/centos-mirror-tools/tarball-dl.sh:        elif [ "$tarball_name" = "mvn.repo.tgz" ]; then
 
[user@0756d97288e1 starlingx]$
 
</source>
 
  
 
=== StarlingX API Existing ===
 
=== StarlingX API Existing ===
Line 126: Line 202:
 
== OpenStack Learning Corner ==
 
== OpenStack Learning Corner ==
  
- https://developer.openstack.org/api-guide/quick-start/
+
* https://developer.openstack.org/api-guide/quick-start/
- https://docs.openstack.org/api/
+
* https://docs.openstack.org/api/
- https://docs.openstack.org/queens/api/
+
* https://docs.openstack.org/queens/api/
- https://github.com/sphinx-contrib/apidoc
+
* https://github.com/sphinx-contrib/apidoc
 +
 
 +
=== Migration ===
 +
 
 +
* https://wiki.openstack.org/wiki/Documentation/Migrate
 +
* https://justwriteclick.com/2015/02/23/state-of-the-migration-to-sphinxrst/
  
 
=== Infrastructure ===
 
=== Infrastructure ===
Line 140: Line 221:
 
** https://github.com/openstack/os-api-ref
 
** https://github.com/openstack/os-api-ref
  
<source lang="sh">
+
== Structure ==
+[testenv:api-ref]
+
 
+# This environment is called from CI scripts to test and publish
+
We saw 2 ways to host API Reference documention:
+# the API Ref to developer.openstack.org.
+
* under doc/source/api
</source>
+
* under api-ref/source/
 +
The second one is the correct one. See the below Nova Gerrit Patch:
 +
* https://review.openstack.org/#/c/230186
  
 
=== Nova Project ===
 
=== Nova Project ===

Latest revision as of 16:10, 11 October 2018

Intro

StarlingX/Docs_and_Infra is working in collaboration with Tech Writers team to document StarlingX APIs, this page reflects the research on what it means for StarlingX.

Analysis

Adding information from Greg Waines who has done some research related to this:

Tracking

Provide upstream API Documentation for the individual StarlingX sub-projects:


The existing API documentation for SYSINV is managed in a very very old mechanism, using maven and wadl files, circa Grizzly.

This API Documentation needs to be converted into the current approach for writing upstream OpenStack API Documentation. i.e. see https://docs.openstack.org/doc-contrib-guide/api-guides.html ( ... see also any current OpenStack Project's rest api documentation, e.g. for glance, https://github.com/openstack/glance/tree/master/api-ref/source )

We will also move the different sections of the big blob of SYSINV API Documentation under the appropriate StarlingX sub-projects:

  • Dcmanager API v1 (Tbd)
    • Move to starlingx-staging/stx-distcloud
  • NFV VIM API v1 (NFV VIM Service REST API)
    • Move to stx-nfv
  • Patching API v1 (Patching REST API)
    • Move to stx-update
  • System Inventory API v1 (System Inventory (SysInv) REST API)
    • Map to stx-metal
      • 6.4. Hosts
      • 6.5. Ports
      • 6.7. CPUs
      • 6.8. Memory
      • 6.11. Disks
      • 6.9. SensorGroup
      • 6.10. Sensor
      • 6.26. LLDP Agents
      • 6.27. LLDP Neighbors
    • Map to stx-config
      • 6.2. System
      • 6.3. Clusters
      • 6.6 Interfaces
      • 6.12. Partitions
      • 6.14. Volume Groups
      • 6.15. Physical Volumes
      • 6.13. Ceph Storage Functions
      • 6.16. Profiles
      • 6.17. DNS
      • 6.18. NTP
      • 6.19. External OAM
      • 6.20. Infrastructure Subnet
      • 6.21. DRBD Configuration
      • 6.22. SNMP Communities
      • 6.23. SNMP Trap Destinations
      • 6.24. Devices
      • 6.25. Service Parameter
      • 6.31. SDN Controllers
      • 6.32. Remote Logging
      • 6.33. Networks
      • 6.34. Address Pools
      • 6.35. Addresses
      • 6.36. Routes
      • 6.37. Storage Backends
      • 6.38. Storage Tiers
      • 6.39. Controller Filesystem
      • 6.40. Ceph Monitors
      • 6.44. System Certificate Configuration
      • 6.45. Custom Firewall Rules
    • Map to stx-fault
      • 11.2 Alarms
      • 11.3 Event Log
      • 11.4 Event Suppression
    • Map to stx-ha
      • 10.2 Services
      • 10.3 Service Nodes
      • 10.4 Service Groups
    • Map to stx-update
      • 6.41. System Health
      • 6.42. Software Loads
      • 6.43. Software Upgrade
    • DELETE
      • 6.46. License
  • Block Storage V2 Extensions API (Extensions to Block Storage REST API)
    • Move to starlingx-staging/stx-python-cinderclient
  • Compute V2 Extensions API (Extensions to Compute REST API)
    • Move to starlingx-staging/stx-nova
  • Image V2 Extensions API (Extensions to Image REST API)
    • Move to starlingx-staging/stx-glance
  • Networking V2 Extensions API (Extensions to Networking REST API)
    • Move to starlingx-staging/stx-neutron
  • Telemetry V2 Extensions API (Extensions to Telemetry REST API)
    • No longer exists ... we've removed these changes in last couple of months.


There are no Extensions to Identity REST API (Keystone) and Orchestration REST API (Heat).

Work Items

  • Storyboard Task 24440: OpenStack API Service Implementation
    • Create ./api-ref/source directory under each StarlingX sub-project for containing API Documentation
    • Update the sub-project's (or StarlingX's) tox.ini file to include a configuration for building the API reference locally
  • Storyboard Task 24441: StarlingX API Documentation Migration
    • Convert the appropriate sections of existing SYSINV API Documentation from maven/wadl to .rst/.yaml format
  • Storyboard Task 24443: OpenStack API Reference Pages Creation
    • Add the api-ref-jobs template to StarlingX project, patch the zuul.d/projects.yaml file stored in openstack-infra/project-config repository.
  • Storyboard Task: To Be Defined
    • Add links to StarlingX sub-project's API DOCs from the API landing page and the OpenStack Governance reference document, projects.yaml.
    • To add a link to the StarlingX sub-project’s API docs to the API landing page, patch the index.rst file stored in the openstack/api-site repository.
    • To ensure the openstack/governance repository has the correct link to your API documentation, patch the reference/projects.yaml file in the openstack/governance repository.

Acceptance Criteria

  • StarlingX API Documentation is converted to current upstream OpenStack API Documentation approach,
  • StarlingX API Documentation are built and available on upstream OpenStack API Documentation sites.

Community Discussion


Starlingx-discuss: StarlingX API Documentation
For this activity we are initially be considering from API Documentation 2 separate efforts for each project:

  • API Guide .. the concepts in the API
  • API Ref .. a reference for the API


Both concepts (API Guide) and the ref (API Ref) need to be be written at the same time. The new OpenStack approach allows for tags to go in the code. The concepts in our APIs are pretty standard and if prioritization is required the API Reference work higher.

StarlingX API

We categorize the StarlingX APIs in 2:

  • Brand New APIs from StarlingX projects
  • Existing APIs from OpenStack projects


StarlingX should not document other OpenStack API's.

StarlingX API Brand New

The projects falling into this category are the following:


All projects in the Flock should be included. I think there is a dependency on some of the code restructuring activities that are underway, we need to make sure these activities don't collide.

StarlingX API SysInv

(You may know this already) The StarlingX APIs (especially for sysinv) are currently documented at: https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc You can use the content as a starting point. However, the mechanism used is outdated using maven and wadl files. So you need to use the more current approach.

Greg Waines did some research on this [Here]

StarlingX API Existing

We have not gone through a deeper review if we are modifying/adding new calls into the OpenStack projects however if we are and we need to document them:

  • There is official OpenStack <Project> API documentation, we can make references to them for the existing calls
  • What about the modifications/additions? Should we document them? What is the best place for this? We were talking in our weekly call about stx-docs is a good place for things without a repo, is this a good example?
  • Any easy way besides "find + grep" to get where those API modifications are happening?

StarlingX API Unit Tests

OpenStack projects includes Unit Tests. To be considered if this is required.

OpenStack Learning Corner

Migration

Infrastructure

Components

Structure

We saw 2 ways to host API Reference documention:

  • under doc/source/api
  • under api-ref/source/

The second one is the correct one. See the below Nova Gerrit Patch:

Nova Project

This is a good project to work with since it has the 2 projects related to APIs, the Guide and Ref, I have also included Specs to see if that applies.

API Guide

This guide covers the concepts in the OpenStack Compute API. For a full reference listing, please see: Compute API Reference.

API Ref

This is a reference for the OpenStack Compute API which is provided by the Nova project. To learn more about the OpenStack Compute API concepts, please refer to the API guide.

Specs

Zuul


Zuul (continuous integration, delivery, and deployment) allows us to enable that automatic publishing based on templates:

- project:
    name: openstack/nova
    templates:
      - openstack-python-jobs
      - openstack-python35-jobs
      - periodic-jobs-with-oslo-master
      - publish-openstack-sphinx-docs
      - release-openstack-server
      - periodic-stable-jobs
      - check-requirements
      - integrated-gate
      - integrated-gate-py35
      - translation-jobs
      - translation-jobs-queens
      - translation-jobs-rocky
      - release-notes-jobs
      - api-guide-jobs
      - api-ref-jobs

Masakari

Git

Masakari Git API Ref

Masakari API Ref

Masakari Zuul


- project:
    name: openstack/masakari
    templates:
      - check-requirements
      - openstack-python-jobs
      - openstack-python35-jobs-nonvoting
      - publish-to-pypi
      - release-notes-jobs
      - api-ref-jobs
      - publish-openstack-sphinx-docs