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

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.

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

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

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.

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.)

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

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

Automatically unassigning due to inactivity.

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

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

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