From 1c6d04901c23c014641623fc0a1641d4f1bde6ac Mon Sep 17 00:00:00 2001 From: Lance Bragstad Date: Thu, 1 Feb 2018 16:25:22 +0000 Subject: [PATCH] Update historical context about the removal of v2.0 This commit updates some of our contributor documentation to accurately describe the v2.0 situation, now that we've removed support for it. Change-Id: Iffd59b81bc269ce67814199b024a034386d74e0c --- doc/source/contributor/http-api.rst | 47 +++++++++++++++-------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/doc/source/contributor/http-api.rst b/doc/source/contributor/http-api.rst index 2f11b6954f..2cea36a1b1 100644 --- a/doc/source/contributor/http-api.rst +++ b/doc/source/contributor/http-api.rst @@ -18,13 +18,13 @@ Identity API v2.0 and v3 History 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. +As of the Queens release, Keystone solely implements the `Identity API v3`_. +Support for `Identity API v2.0`_ has been removed in Queens in favor of +the `Identity API v3`_. + +Identity API v3 is a superset of all the functionality available in the +Identity API v2.0 and several of its extensions, and provides a much more +consistent developer experience. .. _`Identity API v2.0`: https://developer.openstack.org/api-ref/identity/v2/ .. _`Identity API v3`: https://developer.openstack.org/api-ref/identity/v3/ @@ -47,16 +47,6 @@ 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? ================================= @@ -97,10 +87,10 @@ usually both ``[composite:main]`` and ``[composite:admin]``), for example: /v3 = api_v3 ... -Once your pipeline is configured to expose both v2.0 and v3, you need to ensure -that you've configured your service catalog in Keystone correctly. The -simplest, and most ideal, configuration would expose one identity with -unversioned endpoints (note the lack of ``/v2.0/`` or ``/v3/`` in these URLs): +Once your pipeline is configured to expose v3, you need to ensure that you've +configured your service catalog in Keystone correctly. The simplest, and most +ideal, configuration would expose one identity with unversioned endpoints (note +the lack of ``/v2.0/`` or ``/v3/`` in these URLs): - Service (type: ``identity``) @@ -111,6 +101,16 @@ If you were to perform a ``GET`` against either of these endpoints, you would be greeted by an ``HTTP/1.1 300 Multiple Choices`` response, which newer Keystone clients can use to automatically detect available API versions. +.. NOTE:: + + Deploying v3 only requires a single application since administrator and + end-user operations are handled by the same process, and not separated into + two different applications. Depending on how v2.0 was configured, you might + be able to decommission one endpoint. Until users are educated about which + endpoint to use, the former admin API (e.g. using port 35357) and the + public API (e.g. using port 5000) can run the v3 API simulateously and + serve both sets of users. + .. code-block:: bash $ curl -i http://identity:35357/ @@ -233,8 +233,9 @@ merged into one. Instead of isolating functionality into separate applications, all functionality was consolidated into a single application. Each v3 endpoint or API is protected by policy instead. This makes deployment and management of Keystone's infrastructure easier for operators to deploy and for users to -consume. As a result, Keystone deployments interested in only the v3 API are -not required to deploy separate ``admin`` and ``public`` endpoints. +consume. As a result, Keystone deployments are not required to deploy separate +``admin`` and ``public`` endpoints, especially now that the v2.0 API +implementation has been removed. HTTP/1.1 Chunked Encoding =========================