[api] /v3/policy incorrectly shows user_id and project_id as supported parameters

[DWang]

Recently, when I was trying to construct policy related HTTP requests according to the API Complete Reference's Identity v3 API page, the requests I constructed are not accepted by Keystone.

So I used openstackclient to do what I want and got the network packets using wireshark. Then I found that the correct requests and responses are actually not the ones recorded in API Complete Reference.

For example, in order to create a policy, the API details showed in API Complete Reference: http://developer.openstack.org/api-ref-identity-v3.html#createPolicy indicates that "project_id" and "user_id" are needed, while actually they are not! The HTTP requests constructed by openstackclient are same with those in API guide of Keystone, still, taking policy creation as an example, http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html#create-policy

Thus, I think that the policy related API reference in API Complete Reference is out dated and should be modified according to Keystone's api specs.

[Morgan Fainberg (mdrnstm)]

The Policy API in Keystone is very rough and not really usable at the moment (since you can only store blobs of data referenced by a policy_id). We are working to address these issues in this next cycle with significant enhancements. The API site is likely out of date on the keystone policy api as it has never seen real adoption.

I'm going to mark this as a doc bug and something we should look at addressing as we update the policy API and handling in Keystone during liberty.

[Anne Gentle (annegentle)]

Marking incomplete since it needs to be addressed with more info from dev team.

[Jamie Hannaford (jamie-hannaford)]

FWIW, I'm also experiencing this issue. If a sub-API like policies is not stable, should it be part of a stable release?

[Geoff Arnold (geoff-geoffarnold)]

The spec for the Keystone API is at

https://git.openstack.org/cgit/openstack-attic/identity-api/tree/v3/src/markdown/identity-api-v3.md

In addition to the issues raised earlier in the policy-related APIs, there are problems with the core Token methods. For example, in
   POST /v3/auth/tokens
several of the parameters are described as simple xsd:string when they are in fact structured objects. The structure and elements of the objects are not defined; the examples are illustrative but not complete.

[Geoff Arnold (geoff-geoffarnold)]

In Kilo, Keystone introduced support for Hierarchical Multitenancy (HMT). While the API is strictly unchanged (identical syntax, narrowly-interpreted semantics), the descriptive text and examples in the API documentation need to be expanded to cover HMT use cases, including the difference between pre-HMT Keystone and various HMT project/domain topologies. In documenting these aspects of the API, it's critically important to highlight the differences between the Keystone domain/project hierarchy and a more familiar hierarchical namespace (as found in a filesystem or DNS). (Principle of Least Surprise.)

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/230627

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/230627
Committed: https://git.openstack.org/cgit/openstack/api-site/commit/?id=19ba28ae497b120497f4fa661ca2376f57a1ce95
Submitter: Jenkins
Branch: master

commit 19ba28ae497b120497f4fa661ca2376f57a1ce95
Author: Diane Fleming <email address hidden>
Date: Fri Oct 2 15:04:13 2015 -0500

    Update Identity v3 to match spec

    Match the spec here:
    http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html#openstack-identity-api-v3

    Updated calls, parameters, faults, descriptions, and samples for

    * API versions
    * Credentials
    * Domains
    * Endpoints
    * Groups
    * Policies
    * Projects
    * Regions
    * Roles
    * Role assignments
    & Services
    * Tokens
    * Users

    Code samples: Removed unused code samples.

    Change-Id: Ida11399456a4fa6ccff6336a02005192e1897a54
    Closes-Bug: #1448602
    Closes-Bug: #1513587
    Closes-Bug: #1512305

[Lance Bragstad (lbragstad)]

Automatically unassigning due to inactivity.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/385134

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/385134
Committed: https://git.openstack.org/cgit/openstack/keystone/commit/?id=abe6157e5a1cdfba74b1d775630424eff08cbb34
Submitter: Jenkins
Branch: master

commit abe6157e5a1cdfba74b1d775630424eff08cbb34
Author: Steve Martinelli <email address hidden>
Date: Tue Oct 11 15:50:02 2016 -0400

    [api] remove `user_id` and `project_id` from policy

    There is no user ID and project ID support for the /v3/policy
    APIs. The schema [1] validates this.

    [1] https://github.com/openstack/keystone/blob/master/keystone/policy/schema.py

    Change-Id: I53197412c60513756bce42089f5e959d6c9a7c34
    Closes-Bug: #1448602

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/keystone 11.0.0.0b1 development milestone.