summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorEric Fried <efried@us.ibm.com>2017-07-27 08:53:50 -0500
committerEric Fried <efried@us.ibm.com>2017-07-27 16:08:05 +0000
commit8b16c92912f81097a9839fb60dcfc947ae8a92b9 (patch)
tree5e4fe097a7ed6477e3adaad8e90de9cc4e970eb3
parent12bf769d63859000d9c1ef92201924e1ee93d7dd (diff)
Fix service-types-authority schema URL and typos
In the consuming-catalog spec: - Correct the URL pointing to the schema for service-types.json - Minor typographical fixups Change-Id: I4b5b81c64e55a16d05923da447d1c9544aea99b8
Notes
Notes (review): Code-Review+1: Michael McCune <msm@redhat.com> Code-Review+2: Chris Dent <cdent@anticdent.org> Workflow+1: Chris Dent <cdent@anticdent.org> Verified+2: Jenkins Submitted-by: Jenkins Submitted-at: Thu, 27 Jul 2017 16:50:29 +0000 Reviewed-on: https://review.openstack.org/478638 Project: openstack/api-wg Branch: refs/heads/master
-rw-r--r--guidelines/consuming-catalog.rst34
1 files changed, 17 insertions, 17 deletions
diff --git a/guidelines/consuming-catalog.rst b/guidelines/consuming-catalog.rst
index 007281c..53b1e66 100644
--- a/guidelines/consuming-catalog.rst
+++ b/guidelines/consuming-catalog.rst
@@ -47,7 +47,7 @@ service-type
47The user may also wish to express an alteration to the general algorithm: 47The user may also wish to express an alteration to the general algorithm:
48 48
49be-strict 49be-strict
50 Forgo leniant backwards compatibility concessions and be more strict in 50 Forgo lenient backwards compatibility concessions and be more strict in
51 input and output validation. 51 input and output validation.
52 52
53There are several optional pieces of information that the user might know, 53There are several optional pieces of information that the user might know,
@@ -68,10 +68,10 @@ region-name
68 by default would be preferred. 68 by default would be preferred.
69 69
70interface 70interface
71 Which API interface, such as ``public``, ``internal`` or ``admin`` that 71 Which API interface, such as ``public``, ``internal``, or ``admin``
72 the user wants to use. A user can also request a list of interfaces they find 72 the user wants to use. A user can also request a list of interfaces they find
73 acceptable in the order of their preference, such as 73 acceptable in the order of their preference, such as
74 ``['internal', 'public']`` (Optional, defaults to ``public``) 74 ``['internal', 'public']`` (Optional, defaults to ``public``.)
75 75
76service-name 76service-name
77 Arbitrary name given to the service by the deployer. Optional. 77 Arbitrary name given to the service by the deployer. Optional.
@@ -81,19 +81,19 @@ service-name
81 discouraged. However, the Consumer has no way to otherwise mitigate 81 discouraged. However, the Consumer has no way to otherwise mitigate
82 the situation if their Deployer has provided them with a catalog 82 the situation if their Deployer has provided them with a catalog
83 where a ``service-name`` must be used, so ``service-name`` must be 83 where a ``service-name`` must be used, so ``service-name`` must be
84 accepted as input. If ``{be-strict}`` has been requested, a user 84 accepted as input. If ``{be-strict}`` has been requested,
85 supplying ``{service-name}`` should be an error. 85 supplying ``{service-name}`` should be an error.
86 86
87service-id 87service-id
88 Unique identifier for an endpoint in the catalog. Optional. 88 Unique identifier for an endpoint in the catalog. Optional.
89 89
90.. note:: On clouds with well-formed catalogs ``service-id`` should never be 90.. note:: On clouds with well-formed catalogs ``service-id`` should never be
91 needed. If ``{be-strict}`` has been requested, a user supplying 91 needed. If ``{be-strict}`` has been requested, supplying
92 ``{service-id}`` should be an error. 92 ``{service-id}`` should be an error.
93 93
94endpoint-override 94endpoint-override
95 An endpoint for the service that the user has procurred from some other 95 An endpoint for the service that the user has procured from some other
96 source. (Optional, defaults to omitted) 96 source. (Optional, defaults to omitted.)
97 97
98At the end of the discovery process, the user should know the 98At the end of the discovery process, the user should know the
99``{service-endpoint}``, which is the endpoint to use as the root of the 99``{service-endpoint}``, which is the endpoint to use as the root of the
@@ -120,7 +120,7 @@ for historical reasons there are some services that have old service types
120found in the wild. To facilitate moving forward with the correct 120found in the wild. To facilitate moving forward with the correct
121``{service-type}`` names, but also support existing users and installations, 121``{service-type}`` names, but also support existing users and installations,
122the `OpenStack Service Types Authority`_ contains a list of historical 122the `OpenStack Service Types Authority`_ contains a list of historical
123aliases for such services. (see `Consuming Service Types Authority`_ for 123aliases for such services. See `Consuming Service Types Authority`_ for
124information on the data itself. 124information on the data itself.
125 125
126Clients will need a copy of the data published in the 126Clients will need a copy of the data published in the
@@ -142,7 +142,7 @@ The basic process is:
142 142
143#. Retrieve ``{catalog-endpoint}`` from the ``{service-catalog}`` given 143#. Retrieve ``{catalog-endpoint}`` from the ``{service-catalog}`` given
144 some combination of ``{service-type}``, ``{interface}``, ``{service-name}``, 144 some combination of ``{service-type}``, ``{interface}``, ``{service-name}``,
145 ``{region-name}`` and ``{service-id}``. (see :ref:`endpoint-from-catalog`) 145 ``{region-name}`` and ``{service-id}``. (See :ref:`endpoint-from-catalog`.)
146 146
147.. _endpoint-from-catalog: 147.. _endpoint-from-catalog:
148 148
@@ -269,7 +269,7 @@ V2 Catalog Objects:
269The algorithm is: 269The algorithm is:
270 270
271#. Find the objects in the ``{service-catalog}`` that match the requested 271#. Find the objects in the ``{service-catalog}`` that match the requested
272 ``{service-type}``. (see `Match Candidate Entries`_) 272 ``{service-type}``. (See `Match Candidate Entries`_.)
273 273
274#. If ``{service-name}`` was given and the objects remaining have a ``name`` 274#. If ``{service-name}`` was given and the objects remaining have a ``name``
275 field, keep only the ones where ``name`` matches ``{service-name}``. 275 field, keep only the ones where ``name`` matches ``{service-name}``.
@@ -315,19 +315,19 @@ regions that were found.
315 315
316#. From the set of remaining candidate endpoints, find the ones that best 316#. From the set of remaining candidate endpoints, find the ones that best
317 matches the requested ``{service-type}``. 317 matches the requested ``{service-type}``.
318 (see `Find Endpoint Matching Best Service Type`_) 318 (See `Find Endpoint Matching Best Service Type`_.)
319 319
320The remaining ``{candidate-endpoints}`` match the request. If there is more 320The remaining ``{candidate-endpoints}`` match the request. If there is more
321than one of them, use the first, but emit a warning to the user that more 321than one of them, use the first, but emit a warning to the user that more
322than one endpoint was left. If ``{be-strict}`` has been requested, return an 322than one endpoint was left. If ``{be-strict}`` has been requested, return an
323error instead with information about each of the endpoints left in the list. 323error instead with information about each of the endpoints left in the list.
324 324
325.. note:: It would be more correct to throw an error if there is more than one 325.. note:: It would be more correct to raise an error if there is more than one
326 endpoint left, but the keystoneauth library returns the first and 326 endpoint left, but the keystoneauth library returns the first and
327 changing that would break a large number of existing users. If one 327 changing that would break a large number of existing users. If one
328 is writing a completely new library from scratch, or a new major 328 is writing a completely new library from scratch, or a new major
329 version where behavior change is acceptable, defaulting to throwing 329 version where behavior change is acceptable, it is preferable to
330 an error here if there is more than one version left is preferred. 330 raise an error here if there is more than one endpoint left.
331 331
332#. If v2, the ``{catalog-endpoint}`` is the value of ``{interface}URL``. 332#. If v2, the ``{catalog-endpoint}`` is the value of ``{interface}URL``.
333 333
@@ -494,7 +494,7 @@ Given the following catalog:
494 "url": "https://block-storage.example.com/v2" 494 "url": "https://block-storage.example.com/v2"
495 }, 495 },
496 { 496 {
497 "interface": "interal", 497 "interface": "internal",
498 "region": "RegionOne", 498 "region": "RegionOne",
499 "url": "https://block-storage.example.int/v2" 499 "url": "https://block-storage.example.int/v2"
500 } 500 }
@@ -543,7 +543,7 @@ it is important to know a few things:
543 543
544#. The data is published in JSON format at 544#. The data is published in JSON format at
545 https://service-types.openstack.org/service-types.json and has a JSONSchema 545 https://service-types.openstack.org/service-types.json and has a JSONSchema
546 at https://service-types.openstack.org/service-types-schema.json. 546 at https://service-types.openstack.org/published-schema.json.
547 547
548#. The published data contains a version which is date based in 548#. The published data contains a version which is date based in
549 `ISO Date Time Format`_, a sha which contains the git sha of the 549 `ISO Date Time Format`_, a sha which contains the git sha of the
@@ -553,7 +553,7 @@ it is important to know a few things:
553#. The JSON file is served with ETag support and should be considered highly 553#. The JSON file is served with ETag support and should be considered highly
554 cacheable. 554 cacheable.
555 555
556#. The current version of the JSON file should always be the preferred files to 556#. The current version of the JSON file should always be the preferred file to
557 use. 557 use.
558 558
559#. The JSON file is similar to timezone data. It should not be considered 559#. The JSON file is similar to timezone data. It should not be considered