identity-api doc: lack of clarity on X-Auth-Token vs X-Subject-Token

[Dolph Mathews]

This is feedback from simo on IRC.

The identity API doc has a few brief snippets [1] [2] [3] [4] describing what each header is for independently, but never directly compares them to explain when to use each and how to translate usage of one to the other.

Specifically, it would be very beneficial to have a paragraph explaining the "flow" of these token values starting with authentication to usage against a non-Identity API, to online validation against keystone.

[1]: https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/markdown/identity-api-v3.md#required-attributes
[2]: https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/markdown/identity-api-v3.md#tokens
[3]: https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/markdown/identity-api-v3.md#authentication-responses
[4]: https://github.com/openstack/identity-api/blob/master/openstack-identity-api/src/markdown/identity-api-v3.md#validate-token-get-authtokens

[Steve Martinelli (stevemar)]

documentation has been improved in the specs repo: http://specs.openstack.org/openstack/keystone-specs/api/v3/identity-api-v3.html