Bug 1374755

Summary:	[docs] [director] Document the Mistral workflow API
Product:	Red Hat OpenStack	Reporter:	Dougal Matthews <dmatthew>
Component:	documentation	Assignee:	RHOS Documentation Team <rhos-docs>
Status:	CLOSED DEFERRED	QA Contact:	RHOS Documentation Team <rhos-docs>
Severity:	unspecified	Docs Contact:
Priority:	unspecified
Version:	10.0 (Newton)	CC:	adahms, dcadzow, dmacpher, srevivo
Target Milestone:	---	Keywords:	Documentation
Target Release:	10.0 (Newton)
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2018-03-19 14:03:16 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:

Description Dougal Matthews 2016-09-09 14:13:34 UTC

In Newton, TripleO started to use the mistral workflow engine to provide a central place for accessing functionality. This is as a result the API that users may want to use if they want to automate tripleo at a lower level (rather than using the CLI).

This bug is similar to https://bugzilla.redhat.com/show_bug.cgi?id=1374751, except this is at a much lower level and focusing on how to use the API to create and manage plans and deploy them.

There is some basic upstream documentation here:
http://docs.openstack.org/developer/tripleo-common/reference/index.html

And some WIP higher level documentation here:
https://review.openstack.org/358685

The original upstream spec for the work has more detail also but might be a bit out of date in places.
https://specs.openstack.org/openstack/tripleo-specs/specs/mitaka/tripleo-mistral-deployment-library.html

Comment 4 Andrew Dahms 2016-09-12 01:48:45 UTC

Hi Dan,

Thank you for the needinfo request.

From my side, I agree that we do not document the APIs for any of the other components at current, and while I definitely see a use case for doing so for a component like the director, it's a potentially larger effort than we can probably perform in a few weeks.

Moreover, I would also argue that we should investigate automating the generation of some of the required content if possible, and consider the topic of API documentation as a whole in a little more detail before proceeding.

As such, I'm not sure if this is feasible for us to target during the initial OSP 10 schedule, but I'd be keen to hear if Derek has any input as well.

Kind regards,

Andrew

Comment 5 Dan Macpherson 2018-03-19 07:36:07 UTC

Scoping old BZ.

Derek -- We haven't documented APIs in the past but I think this question has come up again recently with another OpenStack project API. What's your take on this BZ?

Comment 6 Derek 2018-03-19 12:52:09 UTC

Same as Andrew really.  We haven't documented API information in OpenStack in the past and from what I'm learning, I'm not sure its something that an installer/admin needs?   I'm thinking it may be more relevant to a developer audience.   

In RHV, where we do have some API documentation, we have used the kind of automated system that Andrew is talking about, where the designers/coders are the ones documenting what they're doing with the API and that information is extracted automagically to create the documents.

Although it's something we may want to do in the future after a bit more research, it's not a high priority on our very full plate at the moment.

Comment 7 Dan Macpherson 2018-03-19 14:03:16 UTC

In that case, I'll close the BZ. This will be something we'll have to evaluate in the future when we can find a method of automating API documentation.