[Starlingx-discuss] StarlingX API Documentation

Waines, Greg Greg.Waines at windriver.com
Wed Aug 8 11:28:05 UTC 2018


See in-lined comments below,
Greg.

From: "Arce Moreno, Abraham" <abraham.arce.moreno at intel.com>
Date: Friday, August 3, 2018 at 12:39 PM
To: "starlingx-discuss at lists.starlingx.io" <starlingx-discuss at lists.starlingx.io>
Subject: [Starlingx-discuss] StarlingX API Documentation

A new goal in collaboration with our Tech Writing team is to document StarlingX APIs,
so we did an initial research on what it means for StarlingX so your feedback is
highly appreciated.

[ OpenStack :: API ]

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

Can we prioritize one over the other?
[Greg]
The concepts in our APIs are pretty standard ... so I would prioritize the API Reference work higher.


[ StarlingX :: API ]

It seems we can categorize the StarlingX APIs in 2:

  - Brand New APIs from StarlingX projects
  - Existing APIs from OpenStack projects
[Greg]
Actually what we currently do ( https://git.openstack.org/cgit/openstack/stx-integ/tree/restapi-doc/restapi-doc ) is

-          Fully document New / StarlingX –specific APIs  (i.e. sysinv APIs), and

-          Document ONLY (non-upstreamed) extensions to existing OpenStack APIs

o   i.e. we did NOT want to duplicate documentation for existing OpenStack APIs



[ StarlingX :: API :: Brand New ]

The projects falling into this category are the following:

  - [0] NFVI Orchestration
  - [1] High Availability/Process Monitoring/Service Management
  - [2] StarlingX System Configuration Management
  - [3] Horizon plugins for new StarlingX services
  - [4] Installation/Update/Patching/Backup/Restore

Can we considered all the above to be included in this API documentation effort?
Are we missing any other?
[Greg]
Yeah basically we would organize it based on the re-partitioned areas of sysinv ....
Actually initially grouped by any new API Endpoints we are introducing due to the sysinv re-partitioning, and
Secondly grouped by functional areas.

[ StarlingX :: API :: Existing ]

All projects living under our starlingx-staging github organization [5] with
upstream contributions [6] e.g. horizon, ceilometer, etc.

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?
[Greg]
As mentioned ... our previous strategy has been to have a separate document chapter that describes
ONLY the extensions that we have done to existing OpenStack APIs.  With the intent being that we
did NOT want to duplicate existing OpenStack API documentation

[ StarlingX :: API :: Unit Tests]

OpenStack projects includes Unit Tests. Is this something we also need to consider
for our StarlingX Bran New APIs?
[Greg]
Not sure what you’re suggesting here ... Unit Tests for our APIs ?

Greg.

[0] http://git.openstack.org/cgit/openstack/stx-nfv/
[1] http://git.openstack.org/cgit/openstack/stx-ha/
[2] http://git.openstack.org/cgit/openstack/stx-config/
[3] http://git.openstack.org/cgit/openstack/stx-gui/
[4] http://git.openstack.org/cgit/openstack/stx-update/
[5] https://github.com/starlingx-staging
[6] http://git.openstack.org/cgit/openstack/stx-upstream/tree/openstack


_______________________________________________
Starlingx-discuss mailing list
Starlingx-discuss at lists.starlingx.io<mailto:Starlingx-discuss at lists.starlingx.io>
http://lists.starlingx.io/cgi-bin/mailman/listinfo/starlingx-discuss

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.starlingx.io/pipermail/starlingx-discuss/attachments/20180808/27886cc8/attachment-0001.html>


More information about the Starlingx-discuss mailing list