Add v2 & v3 API documentation
Keystone itself didn't have much documentation on the APIs it was implementing, so I made space for that documentation first, and then followed it with a first pass on what it takes to move things to v3. Change-Id: I71ee6d3c87b6919eb2f7569069d91f3a00d6337c bp: document-v2-to-v3-transition
This commit is contained in:
parent
1ca41569b3
commit
09f1757db5
187
doc/source/http-api.rst
Normal file
187
doc/source/http-api.rst
Normal file
@ -0,0 +1,187 @@
|
|||||||
|
..
|
||||||
|
Licensed under the Apache License, Version 2.0 (the "License"); you may not
|
||||||
|
use this file except in compliance with the License. You may obtain a copy
|
||||||
|
of the License at
|
||||||
|
|
||||||
|
http://www.apache.org/licenses/LICENSE-2.0
|
||||||
|
|
||||||
|
Unless required by applicable law or agreed to in writing, software
|
||||||
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||||
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||||
|
License for the specific language governing permissions and limitations
|
||||||
|
under the License.
|
||||||
|
|
||||||
|
========
|
||||||
|
HTTP API
|
||||||
|
========
|
||||||
|
|
||||||
|
Specifications
|
||||||
|
==============
|
||||||
|
|
||||||
|
Keystone implements two major HTTP API versions, along with several API
|
||||||
|
extensions that build on top of each core API. The two APIs are specified as
|
||||||
|
`Identity API v2.0`_ and `Identity API v3`_. Each API is specified by a single
|
||||||
|
source of truth to avoid conflicts between documentation and implementation.
|
||||||
|
The original source of truth for the v2.0 API is defined by a set of WADL and
|
||||||
|
XSD files. The original source of truth for the v3 API is defined by
|
||||||
|
documentation.
|
||||||
|
|
||||||
|
.. _`Identity API v2.0`: https://github.com/openstack/identity-api/tree/master/v2.0/src
|
||||||
|
.. _`Identity API v3`: https://github.com/openstack/identity-api/tree/master/v3/src/markdown
|
||||||
|
|
||||||
|
History
|
||||||
|
=======
|
||||||
|
|
||||||
|
You're probably wondering why Keystone does not implement a "v1" API. As a
|
||||||
|
matter of fact, one exists, but it actually predates OpenStack. The v1.x API
|
||||||
|
was an extremely small API documented and implemented by Rackspace for their
|
||||||
|
early public cloud products.
|
||||||
|
|
||||||
|
With the advent of OpenStack, Keystone served to provide a superset of the
|
||||||
|
authentication and multi-tenant authorization models already implemented by
|
||||||
|
Rackspace's public cloud, Nova, and Swift. Thus, Identity API v2.0 was
|
||||||
|
introduced.
|
||||||
|
|
||||||
|
Identity API v3 was established to introduce namespacing for users and projects
|
||||||
|
by using "domains" as a higher-level container for more flexible identity
|
||||||
|
management and fixed a security issue in the v2.0 API (bearer tokens appearing
|
||||||
|
in URLs).
|
||||||
|
|
||||||
|
Should I use v2.0 or v3?
|
||||||
|
========================
|
||||||
|
|
||||||
|
Identity API v3.
|
||||||
|
|
||||||
|
Identity API v3 is a superset of all the functionality available in v2.0 and
|
||||||
|
several of its extensions, and provides a much more consistent developer
|
||||||
|
experience to boot. We're also on the road to deprecating, and ultimately
|
||||||
|
reducing (or dropping) support for, Identity API v2.0.
|
||||||
|
|
||||||
|
How do I migrate from v2.0 to v3?
|
||||||
|
=================================
|
||||||
|
|
||||||
|
I am a deployer
|
||||||
|
---------------
|
||||||
|
|
||||||
|
You'll need to ensure the v3 API is included in your Paste pipeline, usually
|
||||||
|
``etc/keystone-paste.ini``. Our `latest sample configuration`_ includes the v3
|
||||||
|
application pipeline.
|
||||||
|
|
||||||
|
First define a v3 application, which refers to the v3 application factory
|
||||||
|
method:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[app:service_v3]
|
||||||
|
paste.app_factory = keystone.service:v3_app_factory
|
||||||
|
|
||||||
|
Then define a v3 pipeline, which terminates with the v3 application you defined
|
||||||
|
above:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[app:app_v3]
|
||||||
|
pipeline = ... service_v3
|
||||||
|
|
||||||
|
Replace "..." with whatever middleware you'd like to run in front of the API
|
||||||
|
service. Our `latest sample configuration`_ documents our tested
|
||||||
|
recommendations, but your requirements may vary.
|
||||||
|
|
||||||
|
Finally, include the v3 pipeline in at least one ``composite`` application (but
|
||||||
|
usually both ``[composite:main]`` and ``[composite:admin]``), for example:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[composite:main]
|
||||||
|
use = egg:Paste#urlmap
|
||||||
|
/v3 = api_v3
|
||||||
|
...
|
||||||
|
|
||||||
|
.. _`latest sample configuration`: https://github.com/openstack/keystone/blob/master/etc/keystone-paste.ini
|
||||||
|
|
||||||
|
I have a Python client
|
||||||
|
----------------------
|
||||||
|
|
||||||
|
The Keystone community provides first-class support for Python API consumers
|
||||||
|
via our client library, `python-keystoneclient`_. If you're not currently using
|
||||||
|
this library, you should, as it is intended to expose all of our HTTP API
|
||||||
|
functionality. If we're missing something you're looking for, please
|
||||||
|
contribute!
|
||||||
|
|
||||||
|
Adopting `python-keystoneclient`_ should be the easiest way to migrate to
|
||||||
|
Identity API v3.
|
||||||
|
|
||||||
|
.. _`python-keystoneclient`: https://pypi.python.org/pypi/python-keystoneclient/
|
||||||
|
|
||||||
|
I have a non-Python client
|
||||||
|
--------------------------
|
||||||
|
|
||||||
|
You'll likely need to heavily reference our `API documentation`_ to port your
|
||||||
|
application to Identity API v3.
|
||||||
|
|
||||||
|
.. _`API documentation`: https://github.com/openstack/identity-api/blob/master/v3/src/markdown/identity-api-v3.md
|
||||||
|
|
||||||
|
The most common operation would be password-based authentication including a
|
||||||
|
tenant name (i.e. project name) to specify an authorization scope. In Identity
|
||||||
|
API v2.0, this would be a request to ``POST /v2.0/tokens``:
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
|
||||||
|
{
|
||||||
|
"auth": {
|
||||||
|
"passwordCredentials": {
|
||||||
|
"password": "my-password",
|
||||||
|
"username": "my-username"
|
||||||
|
},
|
||||||
|
"tenantName": "project-x"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
And you would get back a JSON blob with an ``access`` -> ``token`` -> ``id``
|
||||||
|
that you could pass to another web service as your ``X-Auth-Token`` header
|
||||||
|
value.
|
||||||
|
|
||||||
|
In Identity API v3, an equivalent request would be to ``POST /v3/auth/tokens``:
|
||||||
|
|
||||||
|
.. code-block:: javascript
|
||||||
|
|
||||||
|
{
|
||||||
|
"auth": {
|
||||||
|
"identity": {
|
||||||
|
"methods": [
|
||||||
|
"password"
|
||||||
|
],
|
||||||
|
"password": {
|
||||||
|
"user": {
|
||||||
|
"domain": {
|
||||||
|
"id": "default"
|
||||||
|
},
|
||||||
|
"name": "my-username",
|
||||||
|
"password": "my-password"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"scope": {
|
||||||
|
"project": {
|
||||||
|
"domain": {
|
||||||
|
"id": "default"
|
||||||
|
},
|
||||||
|
"name": "project-x"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
Note a few key differences when compared to the v2.0 API:
|
||||||
|
|
||||||
|
- A "tenant" in v2.0 became a "project" in v3.
|
||||||
|
- The authentication method (``password``) is explicitly identified.
|
||||||
|
- Both the user name (``my-username``) and project name (``project-x``) are
|
||||||
|
namespaced by an owning domain (where ``id`` = ``default``). The "default"
|
||||||
|
domain exists by default in Keystone, and automatically owns the namespace
|
||||||
|
exposed by Identity API v2.0. Alternatively, you may reference users and
|
||||||
|
projects that exist outside the namespace of the default domain, which are
|
||||||
|
thus inaccessible to the v2.0 API.
|
||||||
|
- In v3, your token is returned to you in an ``X-Subject-Token`` header,
|
||||||
|
instead of as part of the request body. You should still authenticate
|
||||||
|
yourself to other services using the ``X-Auth-Token`` header.
|
@ -65,6 +65,7 @@ Developers Documentation
|
|||||||
developing
|
developing
|
||||||
architecture
|
architecture
|
||||||
middlewarearchitecture
|
middlewarearchitecture
|
||||||
|
http-api
|
||||||
api_curl_examples
|
api_curl_examples
|
||||||
apache-httpd
|
apache-httpd
|
||||||
external-auth
|
external-auth
|
||||||
|
Loading…
Reference in New Issue
Block a user