Bug 1409753 - API documentation confusing
Summary: API documentation confusing
Alias: None
Product: Red Hat OpenStack
Classification: Red Hat
Component: documentation
Version: unspecified
Hardware: Unspecified
OS: Unspecified
Target Milestone: ---
: ---
Assignee: RHOS Documentation Team
QA Contact: RHOS Documentation Team
URL: http://developer.openstack.org/api-re...
Depends On:
TreeView+ depends on / blocked
Reported: 2017-01-03 09:03 UTC by Aleksandar Kostadinov
Modified: 2019-01-24 22:05 UTC (History)
3 users (show)

Fixed In Version:
Doc Type: If docs needed, set a value
Doc Text:
Clone Of:
Last Closed: 2019-01-24 22:05:47 UTC
Target Upstream Version:

Attachments (Terms of Use)

Description Aleksandar Kostadinov 2017-01-03 09:03:10 UTC
Description of problem:
Hello, OpenStack API documentation is confusing for me as a user and causes wastes much more time than reasonable when I try to use it.

For example http://developer.openstack.org/api-ref/compute/?expanded=create-server-detail

There is no indication I can see about API call structure. From the table representation I see `server object` with no link to actual server object structure. Then I see for example `networks` parameter. From table it looks like being specified as a standalone param but in fact it needs to be specified under `server`. There is one exmple which shows where `networks` is to be set, but there is no example about `block_device_mapping_v2`.

I think that for a reasonable user experience, the tables describing call parameters in documentation need to show the proper structure of those params.

As an example I'd provide the OpenShift API [1] where each `object` has a link to its structure instead of a flat parameter list in the request table. You can see how table links to `v1.BuildConfig` and then the table for `v1.BuildConfig` links to other structures.

[1] https://docs.openshift.com/container-platform/latest/rest_api/openshift_v1.html#create-a-buildconfig

Comment 1 Lucy Bopf 2017-06-23 05:30:42 UTC
Bugs against upstream documentation can be reported here:

Comment 2 Aleksandar Kostadinov 2017-06-23 09:48:27 UTC

It seems like we don't maintain an API documentation. I think we should do that, as well fix issues inside it as the one described above.

Comment 3 Derek 2019-01-24 22:05:47 UTC
Please report the issue to the link provided above in comment 1.  The Red Hat documentation group does not work on the upstream docs.  Closing this bug.

Note You need to log in before you can comment on or make changes to this bug.