Bug 1241992

Summary:	API Guide is missing the whole API Content
Product:	Red Hat Satellite	Reporter:	Peter Vreman <peter.vreman>
Component:	Docs API Guide	Assignee:	David O'Brien <daobrien>
Status:	CLOSED NEXTRELEASE	QA Contact:	Tahlia Richardson <trichard>
Severity:	high	Docs Contact:
Priority:	unspecified
Version:	6.1.0	CC:	tlestach
Target Milestone:	Unspecified	Keywords:	Reopened
Target Release:	Unused
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	Bug Fix
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2015-07-23 06:00:30 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:
Embargoed:
Bug Depends On:
Bug Blocks:	1122832

Description Peter Vreman 2015-07-10 15:08:24 UTC

Document URL: https://access.redhat.com/documentation/en-US/Red_Hat_Satellite/6.1/html/API_Guide/index.html

Section Number and Name: 

Describe the issue: 
Missing the content describing the API itself.

Suggestions for c: 

Additional information:

Comment 1 RHEL Program Management 2015-07-10 15:14:21 UTC

Since this issue was entered in Red Hat Bugzilla, the release flag has been
set to ? to ensure that it is properly evaluated for this release.

Comment 2 David O'Brien 2015-07-13 00:09:51 UTC

Hi Peter

Toward the end of Satellite 6.0 dev and start of 6.1 planning, the decision was made to make the "API Guide" a guide to what the API was and how to use APIs from a high level. We only provide descriptions and examples of how to use the different classes of APIs, not descriptions of each.

The entire API is available on any Satellite server at <hostname>./apidoc/v2

The overhead of maintaining up-to-date API doc separate from the server is beyond the scope of our resources.

See https://bugzilla.redhat.com/show_bug.cgi?id=1147710

thanks

Comment 3 Peter Vreman 2015-07-13 07:18:16 UTC

In the Beta document the reference that the API itself is described at http://sat6server/apidoc/v2 is missing.

I would expect a chapter to easily identify it in the Bookmarks section and then have a small paragraph with the text in the previous comment.

Comment 4 Peter Vreman 2015-07-13 07:22:35 UTC

Additionally it is also not mentioned that only API v2 is valid for both Foreman and Katello

The page http://sat6server/apidoc  contains also an API description of Foreman, but it misses that Katello fragments. This is confusing for me as user.

I recommend the following additions:
- add a header and introductions to the apidoc pages
- For Satellite that has Katello plugin as default install the /apidoc shall refer to /apidoc/v2

Comment 5 David O'Brien 2015-07-14 00:03:02 UTC

Comment #3 we can do easily enough. I actually thought there was a bug already to do that but I can't lay eyes on it right now.

Comment #4 will be covered by https://bugzilla.redhat.com/show_bug.cgi?id=1133854 *I think*. I'll refer these two bugs to each other to help tracking.

I can take care of Comment #3 in the doc and the rel note aspect of Comment #4, but updates to the actual apidoc needs to come from eng.

Thanks for the detailed comments.

David