)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":1,"context_line":"Parent:     c1bb3f23 (Describe the publication of service-types-authority data)"},{"line_number":2,"context_line":"Author:     Monty Taylor \u003cmordred@inaugust.com\u003e"},{"line_number":3,"context_line":"AuthorDate: 2017-04-24 11:03:48 -0500"},{"line_number":4,"context_line":"Commit:     Monty Taylor \u003cmordred@inaugust.com\u003e"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":24,"id":"5f201791_12150b49","line":1,"updated":"2017-06-28 22:44:15.000000000","message":"reformat for width","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":12,"context_line":"the present as well as the past. This process has kept in mind what consuming"},{"line_number":13,"context_line":"the recommended discovery process _wants_ to look like in the future and in"},{"line_number":14,"context_line":"calls that out in a few places. The intent would be that the algorithm here"},{"line_number":15,"context_line":"would work for all clouds, but that as clouds and services adopt API-WG"},{"line_number":16,"context_line":"recommendations, the interactions with the clouds would become more"},{"line_number":17,"context_line":"efficient. (so for clients using the complete algorithm they should be"},{"line_number":18,"context_line":"upwards compatible with forthcoming API-WG guidelines and will just"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":28,"id":"7f515b1d_c2dc0a1a","line":15,"updated":"2017-10-05 13:11:18.000000000","message":"s/WG/SIG/ here and below","commit_id":"cd26843a47f02886faa116705d73589834aa5370"}],"guidelines/consuming-catalog.rst":[{"author":{"_account_id":6062,"name":"jichenjc","email":"jichenjc@cn.ibm.com","username":"jichenjc"},"change_message_id":"314cc4adfde74c66542d81eb3fd383dec0a5f93e","unresolved":false,"context_lines":[{"line_number":54,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":55,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":56,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":57,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":58,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":59,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":60,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":13,"id":"3f044301_61498c2f","line":57,"range":{"start_line":57,"start_character":35,"end_line":57,"end_character":41},"updated":"2017-05-10 10:18:30.000000000","message":"stack@devstack:~$ curl -g -X GET http://192.168.123.10/placement/resource_providers/48bdbf93-ec6c-4d94-8c36-a1215ddcc70a/allocations -ack-API-Version: placement LATEST\"  -H \"Content-Type: application/json\" -H \"X-Auth-Token: gAAAAABZEuIz663XM_x2Tahb-g08GmWw-7vc9sA2hqqApRT_P-xHiRfMXNOWGr1z4bhIUi4TibHNhUAsBH8v7tK6h_ntmeNaQVadeXa-YBWNiMG-O5ejJSSsrkJUSmLOefRETjaW3vtJPPWSetTHHqhFYcLygHaXXL6Ql5i4hgGgGoPnnSRHk58\"\n400 Bad Request\n\nThe server could not comply with the request since it is either malformed or otherwise incorrect.\n\n Invalid microversion: invalid version string: LATEST; invalid literal for int() with base 10: \u0027LATEST\u0027  stack@devstack:~$ curl -g -X GET http:ack-API-Version: placement latest\"  -H \"Content-Type: application/json\" -H \"X-Auth-Token: gAAAAABZEuIz663XM_x2Tahb-g08GmWw-7vc9sA2hqqApRT_P-xHiRfMXNOWGr1z4bhIUi4TibHNhUAsBH8v7tK6h_ntmeNaQVadeXa-YBWNiMG-O5ejJSSsrkJUSmLOefRETjaW3vtJPPWSetTHHqhFYcLygHaXXL6Ql5i4hgGgGoPnnSRHk58\"\n{\"resource_provider_generation\": 3, \"allocations\": {\"26d8eee9-fe45-4e3e-a35a-bfff1b965cf1\": {\"resources\": {\"MEMORY_MB\": 512, \"VCPU\": 1, \"DISK_GB\": 1}}}}stack@devstack:~$\n\nseems currently we are using ``latest`` in nova... should we consider to use lower case here?","commit_id":"2b6b0bcf43dadd0296ac372e598734c27a313e01"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1a65c6d796c4dda0506968b781eaa564d4990971","unresolved":false,"context_lines":[{"line_number":54,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":55,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":56,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":57,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":58,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":59,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":60,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":13,"id":"3f044301_873a65c9","line":57,"in_reply_to":"3f044301_61498c2f","updated":"2017-05-10 13:32:02.000000000","message":"Both the compute api and the placement api expect the string \u0027latest\u0027 in the \u0027OpenStack-API-Version\u0027 when requesting the latest version, and right now it is always lowercase. In the microversion spec it is also lowercase: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html#client-interaction\n\nThis is because it\u0027s supposed to be a special token, not really a human string, so case matters.\n\nHowever that may have been a bad decision.\n\nIn any case, the latest used in the header, and the latest being discussed here, though the same concept, are not exactly the same thing.","commit_id":"2b6b0bcf43dadd0296ac372e598734c27a313e01"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a0255895a290a7149727b349538943b3f3a570e6","unresolved":false,"context_lines":[{"line_number":54,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":55,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":56,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":57,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":58,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":59,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":60,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":13,"id":"3f044301_78c36f39","line":57,"in_reply_to":"3f044301_873a65c9","updated":"2017-05-10 22:01:30.000000000","message":"it is a different latest - but we should probably pick the same unique string","commit_id":"2b6b0bcf43dadd0296ac372e598734c27a313e01"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"bcaa4df637cd26cb7ef9bc2fa9c11535f9785521","unresolved":false,"context_lines":[{"line_number":60,"context_line":"At the end of the discovery process, the user should know the following"},{"line_number":61,"context_line":"information."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"If the process was successful:"},{"line_number":64,"context_line":""},{"line_number":65,"context_line":"service-endpoint"},{"line_number":66,"context_line":"  The endpoint to use as the root of the service."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_4077fb3b","side":"PARENT","line":63,"updated":"2017-05-18 12:04:56.000000000","message":"ah, okay this structure now makes more sense, I should have read ahead","commit_id":"e5105cd90b6fcbb911b62854c2ff1fb227e6b7e7"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"12b8579d5e4fec0a2ad6eb66e157ae2d0c1aae58","unresolved":false,"context_lines":[{"line_number":60,"context_line":"At the end of the discovery process, the user should know the following"},{"line_number":61,"context_line":"information."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"If the process was successful:"},{"line_number":64,"context_line":""},{"line_number":65,"context_line":"service-endpoint"},{"line_number":66,"context_line":"  The endpoint to use as the root of the service."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_80b19392","side":"PARENT","line":63,"in_reply_to":"ff0f0b1f_4077fb3b","updated":"2017-05-18 12:36:55.000000000","message":"It was still a good point and I think fixing the earlier version, then making the new change when it makes sense is nicer.","commit_id":"e5105cd90b6fcbb911b62854c2ff1fb227e6b7e7"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"bcaa4df637cd26cb7ef9bc2fa9c11535f9785521","unresolved":false,"context_lines":[{"line_number":347,"context_line":""},{"line_number":348,"context_line":"#. If the requested ``{service-type}`` is an official type from the"},{"line_number":349,"context_line":"   `OpenStack Service Types Authority`_ that has aliases and ``{api-version}``"},{"line_number":350,"context_line":"   was given, look for aliases that end with \"v[0-9]+.*\". If there are any"},{"line_number":351,"context_line":"   aliases with a version suffix that matches the ``{api-version}`` (using"},{"line_number":352,"context_line":"   similar, look for those aliases in the list of candidate endpoints. Return"},{"line_number":353,"context_line":"   the matching endpoint with the highest version."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_60c8bf54","line":350,"updated":"2017-05-18 12:04:56.000000000","message":"this regex means that \u0027volumev3MASTEROFTHEUNIVERSE\u0027 will match. I think you want: \"v[0-9]+\"","commit_id":"2d31298b3f12fa5e99847cbd9645893e8bc5b2ec"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"12b8579d5e4fec0a2ad6eb66e157ae2d0c1aae58","unresolved":false,"context_lines":[{"line_number":347,"context_line":""},{"line_number":348,"context_line":"#. If the requested ``{service-type}`` is an official type from the"},{"line_number":349,"context_line":"   `OpenStack Service Types Authority`_ that has aliases and ``{api-version}``"},{"line_number":350,"context_line":"   was given, look for aliases that end with \"v[0-9]+.*\". If there are any"},{"line_number":351,"context_line":"   aliases with a version suffix that matches the ``{api-version}`` (using"},{"line_number":352,"context_line":"   similar, look for those aliases in the list of candidate endpoints. Return"},{"line_number":353,"context_line":"   the matching endpoint with the highest version."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_0063431c","line":350,"in_reply_to":"ff0f0b1f_60c8bf54","updated":"2017-05-18 12:36:55.000000000","message":"PLEASE GOD can we have volumev3MASTEROFTHEUNIVERSE????","commit_id":"2d31298b3f12fa5e99847cbd9645893e8bc5b2ec"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"dff50de4f03dc9245ccf53a6174eb1d9cca49c50","unresolved":false,"context_lines":[{"line_number":374,"context_line":"   matches one of the aliases and ``{api-version}`` was given and the found"},{"line_number":375,"context_line":"   alias ends with a suffix of \"v[0-9]+$\" and ``{api-version}`` matches the"},{"line_number":376,"context_line":"   version in the suffix (using version matching logic from"},{"line_number":377,"context_line":"   :ref:`find-matching-version`) it is a candidate."},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"Find Best Matching Endpoint"},{"line_number":380,"context_line":"---------------------------"}],"source_content_type":"text/x-rst","patch_set":17,"id":"ff0f0b1f_918015f7","line":377,"updated":"2017-05-24 17:58:02.000000000","message":"this sequence of ands _might_ be easier to consume as a list","commit_id":"1d0c3c3408cfe205f62a9e8e220a7ffaccfe3519"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"0391852bcfd70439186e78842d70cbffd02180bf","unresolved":false,"context_lines":[{"line_number":374,"context_line":"   matches one of the aliases and ``{api-version}`` was given and the found"},{"line_number":375,"context_line":"   alias ends with a suffix of \"v[0-9]+$\" and ``{api-version}`` matches the"},{"line_number":376,"context_line":"   version in the suffix (using version matching logic from"},{"line_number":377,"context_line":"   :ref:`find-matching-version`) it is a candidate."},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"Find Best Matching Endpoint"},{"line_number":380,"context_line":"---------------------------"}],"source_content_type":"text/x-rst","patch_set":17,"id":"ff0f0b1f_81bf79cf","line":377,"in_reply_to":"ff0f0b1f_918015f7","updated":"2017-05-25 19:19:50.000000000","message":"Good idea...","commit_id":"1d0c3c3408cfe205f62a9e8e220a7ffaccfe3519"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"f945e91bcdfe16f4ef364915504e3473bf9f41f0","unresolved":false,"context_lines":[{"line_number":47,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"},{"line_number":48,"context_line":"  input and output validation."},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"skip-version-discovery"},{"line_number":51,"context_line":"  Whether or not the user wants to know additional information about versions."},{"line_number":52,"context_line":"  This is useful if the user has specified an ``{endpoint-override}`` or has"},{"line_number":53,"context_line":"  omitted ``{api-version}`` to tell the process not to bother trying to finding"},{"line_number":54,"context_line":"  the version information. A user requesting version discovery be skipped will"},{"line_number":55,"context_line":"  also not receive any information about available microversions."},{"line_number":56,"context_line":"  (Optional, defaults to False)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"There are several optional pieces of information that the user might know,"},{"line_number":59,"context_line":"or additional constraints the user might wish to express."}],"source_content_type":"text/x-rst","patch_set":19,"id":"ff0f0b1f_8ec56b0d","line":56,"range":{"start_line":50,"start_character":0,"end_line":56,"end_character":31},"updated":"2019-04-22 17:43:29.000000000","message":"Good addition.","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"f945e91bcdfe16f4ef364915504e3473bf9f41f0","unresolved":false,"context_lines":[{"line_number":83,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":84,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":85,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":86,"context_line":"  case the api-version should be ``latest``. Can also be a range of acceptable"},{"line_number":87,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":88,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":89,"context_line":"  want a range or ``latest`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":19,"id":"ff0f0b1f_6ef33775","line":86,"range":{"start_line":86,"start_character":33,"end_line":86,"end_character":43},"updated":"2019-04-22 17:43:29.000000000","message":"Will this obscure the \"CURRENT\" option used in some APIs? or is this strictly microversions which use latest and ignore current?","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"5454374b208f030832ed950eebf2a99523ddb969","unresolved":false,"context_lines":[{"line_number":83,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":84,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":85,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":86,"context_line":"  case the api-version should be ``latest``. Can also be a range of acceptable"},{"line_number":87,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":88,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":89,"context_line":"  want a range or ``latest`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":19,"id":"dfbec78f_60da7878","line":86,"range":{"start_line":86,"start_character":33,"end_line":86,"end_character":43},"in_reply_to":"ff0f0b1f_6ef33775","updated":"2019-05-16 16:27:20.000000000","message":"Strictly microversions.","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"f945e91bcdfe16f4ef364915504e3473bf9f41f0","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":86,"context_line":"  case the api-version should be ``latest``. Can also be a range of acceptable"},{"line_number":87,"context_line":"  versions, which will be given as a comma-separated list, such as"},{"line_number":88,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":89,"context_line":"  want a range or ``latest`` - but from a library and framework perspective,"},{"line_number":90,"context_line":"  things like shade or terraform may have internal logic that can handle more"},{"line_number":91,"context_line":"  than one version of a service and want to use the best version available."}],"source_content_type":"text/x-rst","patch_set":19,"id":"ff0f0b1f_aef82f49","line":88,"range":{"start_line":88,"start_character":2,"end_line":88,"end_character":13},"updated":"2019-04-22 17:43:29.000000000","message":"is ``2.0, 3.0`` ok? Be clear on what the form may be (spaces, no spaces, etc).","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"f945e91bcdfe16f4ef364915504e3473bf9f41f0","unresolved":false,"context_lines":[{"line_number":287,"context_line":""},{"line_number":288,"context_line":"The algorithm is:"},{"line_number":289,"context_line":""},{"line_number":290,"context_line":"#. If ``{api-version}`` was given and ``{service-type}`` ends with a suffix of"},{"line_number":291,"context_line":"   \"v[0-9]+$\" and ``{api-version}`` does not matches the version in the suffix,"},{"line_number":292,"context_line":"   return an error. The user has requested a versioned ``{service-type}`` alias"},{"line_number":293,"context_line":"   and an incompatible ``{api-version}``."},{"line_number":294,"context_line":""},{"line_number":295,"context_line":"#. Find the objects in the ``{service-catalog}`` that match the requested"},{"line_number":296,"context_line":"   ``{service-type}``. (see `Match Candidate Entries`_)"}],"source_content_type":"text/x-rst","patch_set":19,"id":"ff0f0b1f_eeace736","line":293,"range":{"start_line":290,"start_character":1,"end_line":293,"end_character":41},"updated":"2019-04-22 17:43:29.000000000","message":"Hm. I\u0027m not sure if this is clear to me. Provide a concrete example please so that we can be sure behavior is correct.\n\ndoes this mean v3.6 and v3 requests doesn\u0027t work since in the catalog v3.6 is the suffix? (a weird edge case but we are allowing for weird edge cases since we support historical-and/or-non-official-endpoint-types)","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"7de312b7be12497a024fbaef697844f532f2e9cb","unresolved":false,"context_lines":[{"line_number":287,"context_line":""},{"line_number":288,"context_line":"The algorithm is:"},{"line_number":289,"context_line":""},{"line_number":290,"context_line":"#. If ``{api-version}`` was given and ``{service-type}`` ends with a suffix of"},{"line_number":291,"context_line":"   \"v[0-9]+$\" and ``{api-version}`` does not matches the version in the suffix,"},{"line_number":292,"context_line":"   return an error. The user has requested a versioned ``{service-type}`` alias"},{"line_number":293,"context_line":"   and an incompatible ``{api-version}``."},{"line_number":294,"context_line":""},{"line_number":295,"context_line":"#. Find the objects in the ``{service-catalog}`` that match the requested"},{"line_number":296,"context_line":"   ``{service-type}``. (see `Match Candidate Entries`_)"}],"source_content_type":"text/x-rst","patch_set":19,"id":"bfb3d3c7_de699a8b","line":293,"range":{"start_line":290,"start_character":1,"end_line":293,"end_character":41},"in_reply_to":"dfbec78f_e0bd08b7","updated":"2019-05-17 12:29:27.000000000","message":"AH - I see where the confusion is coming. This is strictly to handle legacy service types like volumev2. Basically saying if you ask for service_type\u003dvolumev2, api_version\u003d3 - it\u0027s an error, since v3 of volumev2 is ... well, crazypants.","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b0ed3df29009eeb55733bd5eb690e20a69ef8362","unresolved":false,"context_lines":[{"line_number":287,"context_line":""},{"line_number":288,"context_line":"The algorithm is:"},{"line_number":289,"context_line":""},{"line_number":290,"context_line":"#. If ``{api-version}`` was given and ``{service-type}`` ends with a suffix of"},{"line_number":291,"context_line":"   \"v[0-9]+$\" and ``{api-version}`` does not matches the version in the suffix,"},{"line_number":292,"context_line":"   return an error. The user has requested a versioned ``{service-type}`` alias"},{"line_number":293,"context_line":"   and an incompatible ``{api-version}``."},{"line_number":294,"context_line":""},{"line_number":295,"context_line":"#. Find the objects in the ``{service-catalog}`` that match the requested"},{"line_number":296,"context_line":"   ``{service-type}``. (see `Match Candidate Entries`_)"}],"source_content_type":"text/x-rst","patch_set":19,"id":"dfbec78f_e0bd08b7","line":293,"range":{"start_line":290,"start_character":1,"end_line":293,"end_character":41},"in_reply_to":"ff0f0b1f_eeace736","updated":"2019-05-16 16:36:37.000000000","message":"++ for more clarity on this rule.\n\nfrom my reading it would seem that you are correct about the v3/v3.6 request not working, but i am not sure i understand the intent of the rule well enough.\n\nan example would be great, but i think the language here might need more explanation as well.","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a4e0db46b69b73add208bd75d75e1ec5c13ccecd","unresolved":false,"context_lines":[{"line_number":81,"context_line":""},{"line_number":82,"context_line":"api-version"},{"line_number":83,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":84,"context_line":"  A string with one (``3``) or two (``3.1``) numbers, separated by a dot."},{"line_number":85,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":86,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":87,"context_line":"  A user can desire to work with the latest available version, in which"}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_65fe4438","line":84,"range":{"start_line":84,"start_character":2,"end_line":84,"end_character":73},"updated":"2017-06-01 13:49:19.000000000","message":"Not critical, but clarifying that this is not a decimal number might be helpful. I know that some people are confused that \u00273.9\u0027 is followed by \u00273.10\u0027, because their brains see that as the same as \u00273.1\u0027 (and \u00273.100\u0027, for that matter).","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"2ead9f4e99b96646b700df119a592e07caa2df1f","unresolved":false,"context_lines":[{"line_number":81,"context_line":""},{"line_number":82,"context_line":"api-version"},{"line_number":83,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":84,"context_line":"  A string with one (``3``) or two (``3.1``) numbers, separated by a dot."},{"line_number":85,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":86,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":87,"context_line":"  A user can desire to work with the latest available version, in which"}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_e898e41b","line":84,"in_reply_to":"df140735_65fe4438","updated":"2017-06-01 17:01:47.000000000","message":"There is already a short description of version forms in the microversion guideline [0] that is, naturally, specific to microversions, but is consistent with usage here.  I have not found (quickly) anything else describing the version formats we use, maybe that\u0027s desirable in its own place?\n\n[0] https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html#versioning","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"2f036a151c6fce900c2960d7fae58775851b1e88","unresolved":false,"context_lines":[{"line_number":81,"context_line":""},{"line_number":82,"context_line":"api-version"},{"line_number":83,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":84,"context_line":"  A string with one (``3``) or two (``3.1``) numbers, separated by a dot."},{"line_number":85,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":86,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":87,"context_line":"  A user can desire to work with the latest available version, in which"}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_0424f7ad","line":84,"in_reply_to":"df140735_e898e41b","updated":"2017-06-02 19:13:15.000000000","message":"Ed - good call.\nDean - yah - I agree, I think we should split that into somewhere that\u0027s not just in the microversion doc.","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"2ead9f4e99b96646b700df119a592e07caa2df1f","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":86,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":87,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":88,"context_line":"  case the api-version should be ``latest``."},{"line_number":89,"context_line":"  Can also be a range of acceptable versions, for example ``2.0,3.0``."},{"line_number":90,"context_line":"  The specifics of how the user expresses that range is not important. What is"},{"line_number":91,"context_line":"  important is that there is a difference between a user expressing that they"}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_28a7fc51","line":88,"updated":"2017-06-01 17:01:47.000000000","message":"Existing microversion docs[0] talk about this value only being used for testing.\n\n[0] https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html#client-interaction (warning midway in the section)","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"2f036a151c6fce900c2960d7fae58775851b1e88","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  A user can omit the api-version indicating that they want to use"},{"line_number":86,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":87,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":88,"context_line":"  case the api-version should be ``latest``."},{"line_number":89,"context_line":"  Can also be a range of acceptable versions, for example ``2.0,3.0``."},{"line_number":90,"context_line":"  The specifics of how the user expresses that range is not important. What is"},{"line_number":91,"context_line":"  important is that there is a difference between a user expressing that they"}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_644e1370","line":88,"in_reply_to":"df140735_28a7fc51","updated":"2017-06-02 19:13:15.000000000","message":"AH - that\u0027s worth a clarification. This is one of the places where major and micro are different.","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"c910bfb34d5c9c220ca81f326de7cef70aee7a39","unresolved":false,"context_lines":[{"line_number":46,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":47,"context_line":"  knowing what service they want to discover."},{"line_number":48,"context_line":""},{"line_number":49,"context_line":"The user may also wish to express an alteration to the general algorithm:"},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"be-strict"},{"line_number":52,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_96c9d879","line":49,"updated":"2017-06-21 22:14:36.000000000","message":"we seem to be missing an explanation of how a user would express any of these things. I.e. to what API or function call are these possible arguments?","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"0f1ba9032ed119af8765f1964bb7204baec0db71","unresolved":false,"context_lines":[{"line_number":46,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":47,"context_line":"  knowing what service they want to discover."},{"line_number":48,"context_line":""},{"line_number":49,"context_line":"The user may also wish to express an alteration to the general algorithm:"},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"be-strict"},{"line_number":52,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_a47375e7","line":49,"in_reply_to":"5f201791_96c9d879","updated":"2017-06-22 05:23:56.000000000","message":"That\u0027s a great question! It depends on the library, SDK or framework in question, honestly. Perhaps we should add a note about that? These are intended for this document to be general conceptual user input- not an actual hard API or code specification.","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":46,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":47,"context_line":"  knowing what service they want to discover."},{"line_number":48,"context_line":""},{"line_number":49,"context_line":"The user may also wish to express an alteration to the general algorithm:"},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"be-strict"},{"line_number":52,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_15e054fa","line":49,"in_reply_to":"5f201791_a47375e7","updated":"2017-06-28 22:44:15.000000000","message":"Yeah, so I\u0027ll reiterate what I said earlier [1].  ksa is cited as the \"reference architecture\" for this.  So it would be productive IMO for this document to point to the ksa interfaces that implement the various pieces; and, equally important, to call out the pieces ksa does *not* implement.\n\n[1] https://review.openstack.org/#/c/462814/6/guidelines/consuming-catalog.rst@153","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":55,"context_line":"skip-version-discovery"},{"line_number":56,"context_line":"  Whether or not the user wants to completely skip the version discovery"},{"line_number":57,"context_line":"  process. This is useful if the user has specified an ``{endpoint-override}``"},{"line_number":58,"context_line":"  knows they just want to use whatever is in the catalog. Defaults to False"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"fetch-version-info"},{"line_number":61,"context_line":"  If the user has specified an ``{api-version}`` which can be known to match"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_2d330664","line":58,"range":{"start_line":58,"start_character":2,"end_line":58,"end_character":8},"updated":"2017-06-28 22:44:15.000000000","message":"and knows","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":55,"context_line":"skip-version-discovery"},{"line_number":56,"context_line":"  Whether or not the user wants to completely skip the version discovery"},{"line_number":57,"context_line":"  process. This is useful if the user has specified an ``{endpoint-override}``"},{"line_number":58,"context_line":"  knows they just want to use whatever is in the catalog. Defaults to False"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"fetch-version-info"},{"line_number":61,"context_line":"  If the user has specified an ``{api-version}`` which can be known to match"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_cd3b7235","line":58,"range":{"start_line":58,"start_character":69,"end_line":58,"end_character":75},"updated":"2017-06-28 22:44:15.000000000","message":"period","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  The specifics of how the user expresses that range is not important. What is"},{"line_number":102,"context_line":"  important is that there is a difference between a user expressing that they"},{"line_number":103,"context_line":"  want a specific version (``3.1``) and that they want an open-ended range"},{"line_number":104,"context_line":"  with a minium (``3.1-latest``)."},{"line_number":105,"context_line":"  It may seem strange from an individual user perspective to want a range or"},{"line_number":106,"context_line":"  ``latest`` - but from a library and framework perspective, things like shade"},{"line_number":107,"context_line":"  or terraform may have internal logic that can handle more than one version of"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_7588a821","line":104,"range":{"start_line":104,"start_character":9,"end_line":104,"end_character":15},"updated":"2017-06-28 22:44:15.000000000","message":"minimum","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":153,"context_line":"  If the service supports microversions, what is the minimum microversion the"},{"line_number":154,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"Found values will be referred to in these documents as ``found-{value}`` to"},{"line_number":157,"context_line":"differentiate. So if a user requested an ``{api-version}`` of ``latest``,"},{"line_number":158,"context_line":"``{found-api-version}`` might be ``3.5``."},{"line_number":159,"context_line":""}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_d5789c2c","line":156,"range":{"start_line":156,"start_character":55,"end_line":156,"end_character":72},"updated":"2017-06-28 22:44:15.000000000","message":"Use of curly braces here is kinda confusing alongside L158.","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":161,"context_line":""},{"line_number":162,"context_line":"An error should be returned explaining which part failed. For instance, was a"},{"line_number":163,"context_line":"matching service not found at all or was a matching version not found. If a"},{"line_number":164,"context_line":"matching version was not found, the error should contain a list of version"},{"line_number":165,"context_line":"that were found."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"In the description that follows, each of the above inputs and outputs will"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_b5752035","line":164,"range":{"start_line":164,"start_character":67,"end_line":164,"end_character":74},"updated":"2017-06-28 22:44:15.000000000","message":"versions","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":211,"context_line":"   (see :ref:`endpoint-from-catalog`)"},{"line_number":212,"context_line":""},{"line_number":213,"context_line":"#. If ``{skip-version-discovery}`` is false, perform version discovery using"},{"line_number":214,"context_line":"   the ``{catalog-endpoint}``. (see :ref:`version-discovery-algorithm`)"},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. _endpoint-from-catalog:"},{"line_number":217,"context_line":""}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_cd525267","line":214,"range":{"start_line":214,"start_character":32,"end_line":214,"end_character":33},"updated":"2017-06-28 22:44:15.000000000","message":"Capitalize","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":339,"context_line":""},{"line_number":340,"context_line":"#. If ``{api-version}`` was given and ``{service-type}`` ends with a suffix of"},{"line_number":341,"context_line":"   \"v[0-9]+$\" and ``{api-version}`` does not match that suffix,"},{"line_number":342,"context_line":"   (see :ref:`comparing-major-versions`) STOP. Return an error that the user"},{"line_number":343,"context_line":"   has requested a versioned ``{service-type}`` alias and an incompatible"},{"line_number":344,"context_line":"   ``{api-version}``."},{"line_number":345,"context_line":""}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_557c8cea","line":342,"range":{"start_line":342,"start_character":13,"end_line":342,"end_character":39},"updated":"2017-06-28 22:44:15.000000000","message":"Where\u0027s this reference\u0027s target?","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":392,"context_line":"   matches the requested ``{service-type}``."},{"line_number":393,"context_line":"   (see `Find Endpoint Matching Best Service Type`_)"},{"line_number":394,"context_line":""},{"line_number":395,"context_line":"#. From the set of remaining candidate endpoints, find the ones that best"},{"line_number":396,"context_line":"   matches the best available requested ``{interface}``."},{"line_number":397,"context_line":"   see `Find Endpoint Matching Best Interface`_)"},{"line_number":398,"context_line":""},{"line_number":399,"context_line":"The remaining ``{candidate-endpoints}`` match the request. If there is more"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_95a7c4a8","line":396,"range":{"start_line":395,"start_character":59,"end_line":396,"end_character":56},"updated":"2017-06-28 22:44:15.000000000","message":"Consistency of singular/plural; and did we really want to say \"best\" twice?","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":394,"context_line":""},{"line_number":395,"context_line":"#. From the set of remaining candidate endpoints, find the ones that best"},{"line_number":396,"context_line":"   matches the best available requested ``{interface}``."},{"line_number":397,"context_line":"   see `Find Endpoint Matching Best Interface`_)"},{"line_number":398,"context_line":""},{"line_number":399,"context_line":"The remaining ``{candidate-endpoints}`` match the request. If there is more"},{"line_number":400,"context_line":"than one of them, use the first, but emit a warning to the user that more"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_75b668df","line":397,"range":{"start_line":397,"start_character":3,"end_line":397,"end_character":4},"updated":"2017-06-28 22:44:15.000000000","message":"capitalize","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":445,"context_line":""},{"line_number":446,"context_line":"#. If the requested ``{service-type}``"},{"line_number":447,"context_line":""},{"line_number":448,"context_line":"   * is an official type from the `OpenStack Service Types Authority`_ that"},{"line_number":449,"context_line":"     has aliases"},{"line_number":450,"context_line":"   * ``{api-version}`` was given"},{"line_number":451,"context_line":""},{"line_number":452,"context_line":"   Look for aliases that end with a version suffix of the form \"v[0-9]+$\"."},{"line_number":453,"context_line":"   If there are any aliases with a version suffix that matches the"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_35b0f0dd","line":450,"range":{"start_line":448,"start_character":0,"end_line":450,"end_character":32},"updated":"2017-06-28 22:44:15.000000000","message":"List doesn\u0027t make sense in context of its intro.  This would read better collapsed into a normal sentence.  (C\u0027mon, if you did it with L431-436...)","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":456,"context_line":""},{"line_number":457,"context_line":"#. If the requested ``{service-type}``"},{"line_number":458,"context_line":""},{"line_number":459,"context_line":"   * is an official type in the `OpenStack Service Types Authority`_ that has"},{"line_number":460,"context_line":"     aliases"},{"line_number":461,"context_line":"   * ``{api-version}`` was not given"},{"line_number":462,"context_line":""},{"line_number":463,"context_line":"   check each alias in the order listed to see if it has a matching endpoint"},{"line_number":464,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_d5c65c4a","line":461,"range":{"start_line":459,"start_character":0,"end_line":461,"end_character":36},"updated":"2017-06-28 22:44:15.000000000","message":"ditto","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":461,"context_line":"   * ``{api-version}`` was not given"},{"line_number":462,"context_line":""},{"line_number":463,"context_line":"   check each alias in the order listed to see if it has a matching endpoint"},{"line_number":464,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"},{"line_number":465,"context_line":"   alias that has matching endpoints."},{"line_number":466,"context_line":""},{"line_number":467,"context_line":"#. If the requested ``{service-type}``"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_75db0821","line":464,"range":{"start_line":464,"start_character":54,"end_line":464,"end_character":64},"updated":"2017-06-28 22:44:15.000000000","message":"associated with?","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":464,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"},{"line_number":465,"context_line":"   alias that has matching endpoints."},{"line_number":466,"context_line":""},{"line_number":467,"context_line":"#. If the requested ``{service-type}``"},{"line_number":468,"context_line":""},{"line_number":469,"context_line":"   * is an alias of an official type in the"},{"line_number":470,"context_line":"     `OpenStack Service Types Authority`_"},{"line_number":471,"context_line":""},{"line_number":472,"context_line":"   Return the endpoints that match the official type."},{"line_number":473,"context_line":""}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_55e00ccd","line":470,"range":{"start_line":467,"start_character":0,"end_line":470,"end_character":41},"updated":"2017-06-28 22:44:15.000000000","message":"collapse","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"35fe9a30ba70db8b727c55ae31c20496908ed6dc","unresolved":false,"context_lines":[{"line_number":471,"context_line":""},{"line_number":472,"context_line":"   Return the endpoints that match the official type."},{"line_number":473,"context_line":""},{"line_number":474,"context_line":"#. If the requested ``{service-type}``"},{"line_number":475,"context_line":""},{"line_number":476,"context_line":"   * is an alias of an official type in the"},{"line_number":477,"context_line":"     `OpenStack Service Types Authority`_"},{"line_number":478,"context_line":"   * ``{api-version}`` was given"},{"line_number":479,"context_line":""},{"line_number":480,"context_line":"   look for aliases that end with a version suffix of the form \"v[0-9]+$\". If"},{"line_number":481,"context_line":"   there are any aliases with a version suffix that matches the"}],"source_content_type":"text/x-rst","patch_set":24,"id":"5f201791_f5cef859","line":478,"range":{"start_line":474,"start_character":0,"end_line":478,"end_character":32},"updated":"2017-06-28 22:44:15.000000000","message":"collapse.","commit_id":"dc0e67a0a4690e046b7046a1af810e0df930db29"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":52,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"},{"line_number":53,"context_line":"  input and output validation. Defaults to False."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"skip-version-discovery"},{"line_number":56,"context_line":"  Whether or not the user wants to completely skip the version discovery"},{"line_number":57,"context_line":"  process. This is useful if the user has specified an ``{endpoint-override}``"},{"line_number":58,"context_line":"  knows they just want to use whatever is in the catalog. Defaults to False"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"fetch-version-info"},{"line_number":61,"context_line":"  If the user has specified an ``{api-version}`` which can be known to match"},{"line_number":62,"context_line":"  just from looking at the API, the version discovery process will not fetch"},{"line_number":63,"context_line":"  version information documents. However, the user may want information, such"},{"line_number":64,"context_line":"  as microversion ranges, in which case they can request to fetch the version"},{"line_number":65,"context_line":"  document even with a URL version match. Defaults to False."},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"There are several optional pieces of information that the user might know,"},{"line_number":68,"context_line":"or additional constraints the user might wish to express."}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_4d1e2c0d","line":65,"range":{"start_line":55,"start_character":0,"end_line":65,"end_character":60},"updated":"2017-06-29 18:33:56.000000000","message":"Seems like we don\u0027t really need both of these.  If I\u0027m reading consuming-version-discovery right, fetch-version-info\u003dFalse could be substituted in the one(?) place where skip-version-discovery\u003dTrue is part of the algorithm.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":52,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"},{"line_number":53,"context_line":"  input and output validation. Defaults to False."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"skip-version-discovery"},{"line_number":56,"context_line":"  Whether or not the user wants to completely skip the version discovery"},{"line_number":57,"context_line":"  process. This is useful if the user has specified an ``{endpoint-override}``"},{"line_number":58,"context_line":"  knows they just want to use whatever is in the catalog. Defaults to False"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"fetch-version-info"},{"line_number":61,"context_line":"  If the user has specified an ``{api-version}`` which can be known to match"},{"line_number":62,"context_line":"  just from looking at the API, the version discovery process will not fetch"},{"line_number":63,"context_line":"  version information documents. However, the user may want information, such"},{"line_number":64,"context_line":"  as microversion ranges, in which case they can request to fetch the version"},{"line_number":65,"context_line":"  document even with a URL version match. Defaults to False."},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"There are several optional pieces of information that the user might know,"},{"line_number":68,"context_line":"or additional constraints the user might wish to express."}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_4b04e07b","line":65,"range":{"start_line":55,"start_character":0,"end_line":65,"end_character":60},"in_reply_to":"3f1d235d_4d1e2c0d","updated":"2017-07-12 15:30:44.000000000","message":"We do - but I think we came up with better names in the keystoneauth patches eventually. I\u0027ll update","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":56,"context_line":"  knowing what service they want to discover."},{"line_number":57,"context_line":""},{"line_number":58,"context_line":".. note:: It is worth noting that \u0027user\u0027 is a maleable concept. For instance,"},{"line_number":59,"context_line":"          the shade library performs service discovery on behalf of its users"},{"line_number":60,"context_line":"          so does not expect its users to provide a \u0027service-type\u0027. In that"},{"line_number":61,"context_line":"          case, shade is the \u0027user\u0027 of the keystoneauth library which is the"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_6888bd1e","line":58,"range":{"start_line":58,"start_character":46,"end_line":58,"end_character":54},"updated":"2017-07-12 16:28:17.000000000","message":"malleable","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"91c1d26f11d8e899e347e794a1bf0522763b6206","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":56,"context_line":"  knowing what service they want to discover."},{"line_number":57,"context_line":""},{"line_number":58,"context_line":".. note:: It is worth noting that \u0027user\u0027 is a maleable concept. For instance,"},{"line_number":59,"context_line":"          the shade library performs service discovery on behalf of its users"},{"line_number":60,"context_line":"          so does not expect its users to provide a \u0027service-type\u0027. In that"},{"line_number":61,"context_line":"          case, shade is the \u0027user\u0027 of the keystoneauth library which is the"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_717d411b","line":58,"range":{"start_line":58,"start_character":46,"end_line":58,"end_character":54},"in_reply_to":"1f1a1f67_6888bd1e","updated":"2017-07-12 19:43:56.000000000","message":"No, I think he means it\u0027s not female-able.\n\n:-P","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":56,"context_line":"  knowing what service they want to discover."},{"line_number":57,"context_line":""},{"line_number":58,"context_line":".. note:: It is worth noting that \u0027user\u0027 is a maleable concept. For instance,"},{"line_number":59,"context_line":"          the shade library performs service discovery on behalf of its users"},{"line_number":60,"context_line":"          so does not expect its users to provide a \u0027service-type\u0027. In that"},{"line_number":61,"context_line":"          case, shade is the \u0027user\u0027 of the keystoneauth library which is the"},{"line_number":62,"context_line":"          discovery implementation. It is definitely not required that all"},{"line_number":63,"context_line":"          consumers of OpenStack clouds know all of these things."},{"line_number":64,"context_line":""},{"line_number":65,"context_line":"Optional Filters"},{"line_number":66,"context_line":"----------------"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_6b88b71e","line":63,"range":{"start_line":58,"start_character":0,"end_line":63,"end_character":65},"updated":"2017-07-12 16:28:17.000000000","message":"Not sure if this is the right place for this note.  Perhaps in the intro after the note about \"object\" on L22-3.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"91c1d26f11d8e899e347e794a1bf0522763b6206","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  Required. It is impossible for a user to consume service discovery without"},{"line_number":56,"context_line":"  knowing what service they want to discover."},{"line_number":57,"context_line":""},{"line_number":58,"context_line":".. note:: It is worth noting that \u0027user\u0027 is a maleable concept. For instance,"},{"line_number":59,"context_line":"          the shade library performs service discovery on behalf of its users"},{"line_number":60,"context_line":"          so does not expect its users to provide a \u0027service-type\u0027. In that"},{"line_number":61,"context_line":"          case, shade is the \u0027user\u0027 of the keystoneauth library which is the"},{"line_number":62,"context_line":"          discovery implementation. It is definitely not required that all"},{"line_number":63,"context_line":"          consumers of OpenStack clouds know all of these things."},{"line_number":64,"context_line":""},{"line_number":65,"context_line":"Optional Filters"},{"line_number":66,"context_line":"----------------"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_91b69dd9","line":63,"range":{"start_line":58,"start_character":0,"end_line":63,"end_character":65},"in_reply_to":"1f1a1f67_6b88b71e","updated":"2017-07-12 19:43:56.000000000","message":"Agreed. If you\u0027re using Shade, you\u0027re not doing version discovery; Shade is. This should be seen as a guide for people developing tools like SDKs or Shade or similar.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":76,"context_line":"  If ``{be-strict}`` (see below) has been given, ``{region-name}`` is required."},{"line_number":77,"context_line":""},{"line_number":78,"context_line":".. note:: It is highly recommended that ``{region-name}`` always be required"},{"line_number":79,"context_line":"          to protect against single-region clouds adding a region in the"},{"line_number":80,"context_line":"          future. However, the canonical OpenStack implementation keystoneauth"},{"line_number":81,"context_line":"          today allows region-name to be omitted and there are a large number"},{"line_number":82,"context_line":"          of clouds in existence with a single region named ``RegionOne``."}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_cb058b7c","line":79,"range":{"start_line":79,"start_character":10,"end_line":79,"end_character":65},"updated":"2017-07-12 16:28:17.000000000","message":"Makes it sound like specifying ``{region-name}`` will prevent single-region clouds from adding a region in the future.  Perhaps, \"...in case single-region clouds add a region...\" ?","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":86,"context_line":"          discouraged."},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"interface"},{"line_number":89,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":90,"context_line":"  the user wants to use. A user should be able to request a list of interfaces"},{"line_number":91,"context_line":"  they find acceptable in the order of their preference, such as"},{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_6b39d73f","line":89,"range":{"start_line":89,"start_character":68,"end_line":89,"end_character":73},"updated":"2017-07-12 16:28:17.000000000","message":"comma after the list; and strike `that`.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":89,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":90,"context_line":"  the user wants to use. A user should be able to request a list of interfaces"},{"line_number":91,"context_line":"  they find acceptable in the order of their preference, such as"},{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_eb1de7bd","line":92,"range":{"start_line":92,"start_character":28,"end_line":92,"end_character":29},"updated":"2017-07-12 16:28:17.000000000","message":"period","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":91,"context_line":"  they find acceptable in the order of their preference, such as"},{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_6e456517","line":94,"updated":"2017-07-12 16:28:17.000000000","message":"This whole section is really confusing.  It seems like you\u0027re sometimes using endpoint-version to refer to the specific behavior of Adapter/endpoint_filter.version, and sometimes using it to talk about the general concept of specifying a version range.\n\nParticularly in light of our discussion about discouraging use of Adapter/endpoint_filter.version and encouraging min/max only, we should structure this section more like:\n\n- Introduce just min-endpoint-version \u0026 max-endpoint-version, describe their allowed formats (\u0027X.Y\u0027, \u0027latest\u0027, \u0027X.latest\u0027) and default behaviors if either/both omitted.\n- Talk about the fact that legacy ksa also supports a thing called \u0027version\u0027, which is implicitly min-endpoint-version\u003d{version}, max-endpoint-version\u003d\u0027major{version}.latest\u0027.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_cbefcb85","line":95,"updated":"2017-07-12 16:28:17.000000000","message":"Double-backquoting/curly-bracing of keywords throughout this section.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"91c1d26f11d8e899e347e794a1bf0522763b6206","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  Each endpoint version is a string with one (``3``) or two (``3.1``) numbers,"},{"line_number":102,"context_line":"  separated by a dot."},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"},{"line_number":105,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"  A user can omit the endpoint-version indicating that they want to use"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_91045d7d","line":104,"range":{"start_line":104,"start_character":2,"end_line":104,"end_character":64},"updated":"2017-07-12 19:43:56.000000000","message":"Thanks for this. I understand this; you understand this; but others...","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":126,"context_line":"  or terraform may have internal logic that can handle more than one version of"},{"line_number":127,"context_line":"  a service and want to use the best version available."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":".. note:: Guidance around \u0027latest\u0027 is different from that found in"},{"line_number":130,"context_line":"          :ref:`microversion-client-interaction`. It is acceptable for a client"},{"line_number":131,"context_line":"          library or framework to be interested in the latest version available"},{"line_number":132,"context_line":"          but such a specification is internal and not sent to the server. In"},{"line_number":133,"context_line":"          the client case with Major versions, \u0027latest\u0027 acts as an input to"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_ee69758b","line":130,"range":{"start_line":129,"start_character":10,"end_line":130,"end_character":49},"updated":"2017-07-12 16:28:17.000000000","message":"Are we crisscrossing endpoint-version and microversion concepts here?","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":142,"context_line":"          the situation if their Deployer has provided them with a catalog"},{"line_number":143,"context_line":"          where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":144,"context_line":"          accepted as input."},{"line_number":145,"context_line":"          If ``{be-strict}`` (see below) has been requested, a user supplying"},{"line_number":146,"context_line":"          ``{service-name}`` should be an error."},{"line_number":147,"context_line":""},{"line_number":148,"context_line":"service-id"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_4e7d091b","line":145,"range":{"start_line":145,"start_character":61,"end_line":145,"end_character":67},"updated":"2017-07-12 16:28:17.000000000","message":"Strike.  The user isn\u0027t an error, despite what cdent may think.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"91c1d26f11d8e899e347e794a1bf0522763b6206","unresolved":false,"context_lines":[{"line_number":142,"context_line":"          the situation if their Deployer has provided them with a catalog"},{"line_number":143,"context_line":"          where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":144,"context_line":"          accepted as input."},{"line_number":145,"context_line":"          If ``{be-strict}`` (see below) has been requested, a user supplying"},{"line_number":146,"context_line":"          ``{service-name}`` should be an error."},{"line_number":147,"context_line":""},{"line_number":148,"context_line":"service-id"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_f17831f9","line":145,"range":{"start_line":145,"start_character":61,"end_line":145,"end_character":67},"in_reply_to":"1f1a1f67_4e7d091b","updated":"2017-07-12 19:43:56.000000000","message":"...or \"should result in an error\"","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":159,"context_line":"Discovery Behavior Modifiers"},{"line_number":160,"context_line":"----------------------------"},{"line_number":161,"context_line":""},{"line_number":162,"context_line":"The user may also wish to express a alterations to the general algorithm."},{"line_number":163,"context_line":"Implementations may present these flags under any name that makes sense,"},{"line_number":164,"context_line":"or may choose to not present them as behavioral modification options at all."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_2e7acd23","line":162,"range":{"start_line":162,"start_character":34,"end_line":162,"end_character":35},"updated":"2017-07-12 16:28:17.000000000","message":"strike","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":164,"context_line":"or may choose to not present them as behavioral modification options at all."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"be-strict"},{"line_number":167,"context_line":"  Forgo leniant backwards compatibility concessions and be more strict in"},{"line_number":168,"context_line":"  input and output validation. Defaults to False."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"skip-discovery"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_0e77113d","line":167,"range":{"start_line":167,"start_character":8,"end_line":167,"end_character":15},"updated":"2017-07-12 16:28:17.000000000","message":"lenient","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":168,"context_line":"  input and output validation. Defaults to False."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"skip-discovery"},{"line_number":171,"context_line":"  If the user wants to completely skip the version discovery process even if"},{"line_number":172,"context_line":"  logic would otherwise do it. This is useful if the user has specified an"},{"line_number":173,"context_line":"  ``{endpoint-override}`` or they know they just want to use whatever is in"},{"line_number":174,"context_line":"  the catalog and do not need additional metadata about the endpoint. Defaults"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_ae937d4f","line":171,"range":{"start_line":171,"start_character":2,"end_line":171,"end_character":23},"updated":"2017-07-12 16:28:17.000000000","message":"Strike","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":172,"context_line":"  logic would otherwise do it. This is useful if the user has specified an"},{"line_number":173,"context_line":"  ``{endpoint-override}`` or they know they just want to use whatever is in"},{"line_number":174,"context_line":"  the catalog and do not need additional metadata about the endpoint. Defaults"},{"line_number":175,"context_line":"  to False"},{"line_number":176,"context_line":""},{"line_number":177,"context_line":"fetch-version-information"},{"line_number":178,"context_line":"  If the user has specified an ``{endpoint-version}`` which can be known to"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_6e9d6558","line":175,"updated":"2017-07-12 16:28:17.000000000","message":"period","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":181,"context_line":"  information, such as microversion ranges. Using"},{"line_number":182,"context_line":"  ``{fetch-version-information}`` allows them to request that the version"},{"line_number":183,"context_line":"  document be fetched even when an optimization in the process would otherwise"},{"line_number":184,"context_line":"  allow fetching the document to be skipped. Defaults to False."},{"line_number":185,"context_line":""},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"Discovery Results"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_2ec88d53","line":184,"range":{"start_line":184,"start_character":2,"end_line":184,"end_character":43},"updated":"2017-07-12 16:28:17.000000000","message":"or \"skip fetching the document\"","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":204,"context_line":"  If the service supports microversions, what is the minimum microversion the"},{"line_number":205,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"Found values will be referred to in these documents as ``found-{value}`` to"},{"line_number":208,"context_line":"differentiate. So if a user requested an ``{endpoint-version}`` of ``latest``,"},{"line_number":209,"context_line":"``{found-endpoint-version}`` might be ``3.5``."},{"line_number":210,"context_line":""}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_a81ed56d","line":207,"range":{"start_line":207,"start_character":55,"end_line":207,"end_character":72},"updated":"2017-07-12 16:28:17.000000000","message":"The way curly braces are abused here is pretty confusing.  Not sure I have a better suggestion; but the point should be that the outermost part of the token should be surrounded with curly braces; and the `value` bit should be indicated as being variable.  Perhaps\n\n ``{found-*value*}``\n\n?\n\nHaving said that, nowhere in this document is the {found-*} syntax actually used.  It\u0027s used in consuming-version-discovery.rst, but only for {found-endpoint-version}, so it\u0027s probably unnecessary to make this general statement at all.","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An error should be returned explaining which part failed. For instance, was a"},{"line_number":214,"context_line":"matching service not found at all or was a matching version not found. If a"},{"line_number":215,"context_line":"matching version was not found, the error should contain a list of version"},{"line_number":216,"context_line":"that were found."},{"line_number":217,"context_line":""},{"line_number":218,"context_line":"In the description that follows, each of the above inputs and outputs will"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_c8dc711a","line":215,"range":{"start_line":215,"start_character":67,"end_line":215,"end_character":74},"updated":"2017-07-12 16:28:17.000000000","message":"versions","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":443,"context_line":"   matches the requested ``{service-type}``."},{"line_number":444,"context_line":"   (see `Find Endpoint Matching Best Service Type`_)"},{"line_number":445,"context_line":""},{"line_number":446,"context_line":"#. From the set of remaining candidate endpoints, find the ones that best"},{"line_number":447,"context_line":"   matches the best available requested ``{interface}``."},{"line_number":448,"context_line":"   see `Find Endpoint Matching Best Interface`_)"},{"line_number":449,"context_line":""},{"line_number":450,"context_line":"The remaining ``{candidate-endpoints}`` match the request. If there is more"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_e844cdb9","line":447,"range":{"start_line":446,"start_character":59,"end_line":447,"end_character":19},"updated":"2017-07-12 16:28:17.000000000","message":"Consistency of singular/plural; and did we really want to say \"best\" twice?","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":496,"context_line":""},{"line_number":497,"context_line":"#. If the requested ``{service-type}``"},{"line_number":498,"context_line":""},{"line_number":499,"context_line":"   * is an official type from the `OpenStack Service Types Authority`_ that"},{"line_number":500,"context_line":"     has aliases"},{"line_number":501,"context_line":"   * ``{endpoint-version}`` was given"},{"line_number":502,"context_line":""},{"line_number":503,"context_line":"   Look for aliases that end with a version suffix of the form \"v[0-9]+$\"."},{"line_number":504,"context_line":"   If there are any aliases with a version suffix that matches the"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_e84badad","line":501,"range":{"start_line":499,"start_character":0,"end_line":501,"end_character":37},"updated":"2017-07-12 16:28:17.000000000","message":"This doesn\u0027t make sense as a list; better to collapse into a single sentence (like L482-7).","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":507,"context_line":""},{"line_number":508,"context_line":"#. If the requested ``{service-type}``"},{"line_number":509,"context_line":""},{"line_number":510,"context_line":"   * is an official type in the `OpenStack Service Types Authority`_ that has"},{"line_number":511,"context_line":"     aliases"},{"line_number":512,"context_line":"   * ``{endpoint-version}`` was not given"},{"line_number":513,"context_line":""},{"line_number":514,"context_line":"   check each alias in the order listed to see if it has a matching endpoint"},{"line_number":515,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_c8c6b117","line":512,"range":{"start_line":510,"start_character":0,"end_line":512,"end_character":41},"updated":"2017-07-12 16:28:17.000000000","message":"ditto","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":512,"context_line":"   * ``{endpoint-version}`` was not given"},{"line_number":513,"context_line":""},{"line_number":514,"context_line":"   check each alias in the order listed to see if it has a matching endpoint"},{"line_number":515,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"},{"line_number":516,"context_line":"   alias that has matching endpoints."},{"line_number":517,"context_line":""},{"line_number":518,"context_line":"#. If the requested ``{service-type}``"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_28008534","line":515,"range":{"start_line":515,"start_character":54,"end_line":515,"end_character":64},"updated":"2017-07-12 16:28:17.000000000","message":"associated with?","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":515,"context_line":"   from the candidate endpoints. Return the endpoints that match the first"},{"line_number":516,"context_line":"   alias that has matching endpoints."},{"line_number":517,"context_line":""},{"line_number":518,"context_line":"#. If the requested ``{service-type}``"},{"line_number":519,"context_line":""},{"line_number":520,"context_line":"   * is an alias of an official type in the"},{"line_number":521,"context_line":"     `OpenStack Service Types Authority`_"},{"line_number":522,"context_line":""},{"line_number":523,"context_line":"   Return the endpoints that match the official type."},{"line_number":524,"context_line":""}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_c89471eb","line":521,"range":{"start_line":518,"start_character":0,"end_line":521,"end_character":41},"updated":"2017-07-12 16:28:17.000000000","message":"collapse","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":522,"context_line":""},{"line_number":523,"context_line":"   Return the endpoints that match the official type."},{"line_number":524,"context_line":""},{"line_number":525,"context_line":"#. If the requested ``{service-type}``"},{"line_number":526,"context_line":""},{"line_number":527,"context_line":"   * is an alias of an official type in the"},{"line_number":528,"context_line":"     `OpenStack Service Types Authority`_"},{"line_number":529,"context_line":"   * ``{endpoint-version}`` was given"},{"line_number":530,"context_line":""},{"line_number":531,"context_line":"   look for aliases that end with a version suffix of the form \"v[0-9]+$\". If"},{"line_number":532,"context_line":"   there are any aliases with a version suffix that matches the"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_a8993520","line":529,"range":{"start_line":525,"start_character":0,"end_line":529,"end_character":37},"updated":"2017-07-12 16:28:17.000000000","message":"collapse","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":537,"context_line":""},{"line_number":538,"context_line":"#. If there are no matching endpoints, return an error."},{"line_number":539,"context_line":""},{"line_number":540,"context_line":".. note:: The case where an alias was requested and no endpoint-version was"},{"line_number":541,"context_line":"          given and there is a different alias in the catalog is not safe and"},{"line_number":542,"context_line":"          so is treated as a lack of matching endpoint on purpose. Many of the"},{"line_number":543,"context_line":"          aliases carry an implied version, so absent a requested"}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_8ee681e8","line":540,"range":{"start_line":540,"start_character":55,"end_line":540,"end_character":71},"updated":"2017-07-12 16:28:17.000000000","message":"quoteyquote","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"1cbf7bebb8a8dfa19a9e60ce59483e2c300a39ef","unresolved":false,"context_lines":[{"line_number":541,"context_line":"          given and there is a different alias in the catalog is not safe and"},{"line_number":542,"context_line":"          so is treated as a lack of matching endpoint on purpose. Many of the"},{"line_number":543,"context_line":"          aliases carry an implied version, so absent a requested"},{"line_number":544,"context_line":"          endpoint-version from the user, returning an endpoint different than"},{"line_number":545,"context_line":"          the one explicitly requested has a high chance of not being the"},{"line_number":546,"context_line":"          endpoint the user expected."},{"line_number":547,"context_line":""}],"source_content_type":"text/x-rst","patch_set":27,"id":"1f1a1f67_4ed069f8","line":544,"range":{"start_line":544,"start_character":10,"end_line":544,"end_character":26},"updated":"2017-07-12 16:28:17.000000000","message":"ditto","commit_id":"7c86926d6127345d054b1b69f14e3a58ce624cda"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_22cbde4a","line":95,"updated":"2017-10-05 13:11:18.000000000","message":"After I got to reviewing the next file, I got hopelessly confused. Is it a major or a micro version? It feels like you have a mix of both here.. E.g. you talk about discovering this \"version\" from an endpoint, and at the same time this section seem to be talking about microversions, as you talk about ranges..","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":92,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_29485eca","line":95,"in_reply_to":"7f515b1d_22cbde4a","updated":"2017-10-05 16:28:48.000000000","message":"This is all about major versions.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_02da2216","line":97,"updated":"2017-10-05 13:11:18.000000000","message":"I slightly disagree here. I think it may be more useful to accept a list of versions rather than a range. A range means that the Application was tested and proved working against all versions in between. This is challenging in practice, and may be not too useful in the end. What we may end up in reality, is people testing only with min and max versions, assuming the versions in between will work. This is not a correct assumption from our standpoint, as we allow changes to be breaking. So, I\u0027d prefer [\u00273.2\u0027, \u00273.10\u0027] to mean \"either 3.2 or 3.10\", rather than \"any version between 3.2 and 3.10\".","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_8937524e","line":97,"in_reply_to":"7f515b1d_02da2216","updated":"2017-10-05 16:28:48.000000000","message":"Yah - what you said makes sense for microversions, but not for major versions because of the way they work. For this we\u0027re talking:\n\n  I want a block-storage endpoint and I understand v2 and v3 but not v1.\n\nDEFINITELY needs better clarity in the text.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0a1490f4a48a3a43e1a6d44ffe47e7f57e47e9ba","unresolved":false,"context_lines":[{"line_number":94,"context_line":"endpoint-version OR min-endpoint-version, max-endpoint-version"},{"line_number":95,"context_line":"  The version of the service the user desires to work with. Optional."},{"line_number":96,"context_line":""},{"line_number":97,"context_line":"  An endpoint-version is inherently a range with a minimum and a maximum value."},{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f96bb07_7fb447f2","line":97,"in_reply_to":"7f515b1d_8937524e","updated":"2018-01-18 15:20:32.000000000","message":"A list certainly seems better; perhaps it could also include a range, e.g.:\n\n  [\u00272.0\u0027, \u00272.4-2.12\u0027]","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"  Each endpoint version is a string with one (``3``) or two (``3.1``) numbers,"},{"line_number":102,"context_line":"  separated by a dot."},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_e2d4a6eb","line":101,"updated":"2017-10-05 13:11:18.000000000","message":"This guide does not cover what just \"3\" should mean. Is it up to services to decide?","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":98,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"  Each endpoint version is a string with one (``3``) or two (``3.1``) numbers,"},{"line_number":102,"context_line":"  separated by a dot."},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_c9166aa8","line":101,"in_reply_to":"7f515b1d_e2d4a6eb","updated":"2017-10-05 16:28:48.000000000","message":"Will fix - and no, it is not.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"  Each endpoint version is a string with one (``3``) or two (``3.1``) numbers,"},{"line_number":102,"context_line":"  separated by a dot."},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"},{"line_number":105,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_c2052a7c","line":102,"updated":"2017-10-05 13:11:18.000000000","message":"nit: from Python standpoint, we should accept tuples too, but I guess this document is too generic?","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":99,"context_line":"  parameters is an implementation detail."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"  Each endpoint version is a string with one (``3``) or two (``3.1``) numbers,"},{"line_number":102,"context_line":"  separated by a dot."},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"},{"line_number":105,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_29217efc","line":102,"in_reply_to":"7f515b1d_c2052a7c","updated":"2017-10-05 16:28:48.000000000","message":"Yah - keystoneauth actually does accept tuples, but this is intended to be a description of semantics, not language impl details.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":105,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"  A user can omit the endpoint-version indicating that they want to use"},{"line_number":108,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":111,"context_line":"  case the endpoint-version should be ``latest``. If min-endpoint-version is"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_a208ee90","line":108,"updated":"2017-10-05 13:11:18.000000000","message":"mmmm, versions are not in {service-catalog}, are they? I think you meant \"they want to use whatever version is the default for the service\"?","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":105,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"  A user can omit the endpoint-version indicating that they want to use"},{"line_number":108,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":111,"context_line":"  case the endpoint-version should be ``latest``. If min-endpoint-version is"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_69dad6e9","line":108,"in_reply_to":"7f515b1d_a208ee90","updated":"2017-10-05 16:28:48.000000000","message":"Versions are not in the service-catalog, but many services by historical convention put versioned endpoints in the catalog.\n\nOmitting a version from an endpoint request means \"please give me whichever endpoint I get by following what is in the catalog without trying to find a \"newer\" one if it exists.\n\nA specific example is clouds that have put a v2 endpoint in the catalog for block-storage but run a cinder that has v3 support. the user not requesting a major api version will mean that version discovery will simply grab the endpoint in the catalog and consider that one \"best\" and will not go searching the service\u0027s version discovery document for a more current endpoint.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":113,"context_line":""},{"line_number":114,"context_line":"  A version can be specified with a minor value of ``latest`` to indicate"},{"line_number":115,"context_line":"  the highest minor version of a given major version. For instance,"},{"line_number":116,"context_line":"  ``3.latest`` would match the highest of ``3.3`` and ``3.4`` but not ``4.0``."},{"line_number":117,"context_line":""},{"line_number":118,"context_line":"  If the parameter is presented as a single string, a single value should be"},{"line_number":119,"context_line":"  interpreted as if ``{min-endpoint-version}`` is the value given and"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_82ff3266","line":116,"updated":"2017-10-05 13:11:18.000000000","message":"++ I like this (though Ironic does not implement it..)","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":113,"context_line":""},{"line_number":114,"context_line":"  A version can be specified with a minor value of ``latest`` to indicate"},{"line_number":115,"context_line":"  the highest minor version of a given major version. For instance,"},{"line_number":116,"context_line":"  ``3.latest`` would match the highest of ``3.3`` and ``3.4`` but not ``4.0``."},{"line_number":117,"context_line":""},{"line_number":118,"context_line":"  If the parameter is presented as a single string, a single value should be"},{"line_number":119,"context_line":"  interpreted as if ``{min-endpoint-version}`` is the value given and"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_e9efe684","line":116,"in_reply_to":"7f515b1d_82ff3266","updated":"2017-10-05 16:28:48.000000000","message":"Ironic does not have to - this is ALL client-side consumption and how to match information returned from version discovery docs.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0a1490f4a48a3a43e1a6d44ffe47e7f57e47e9ba","unresolved":false,"context_lines":[{"line_number":159,"context_line":"Discovery Behavior Modifiers"},{"line_number":160,"context_line":"----------------------------"},{"line_number":161,"context_line":""},{"line_number":162,"context_line":"The user may also wish to express a alterations to the general algorithm."},{"line_number":163,"context_line":"Implementations may present these flags under any name that makes sense,"},{"line_number":164,"context_line":"or may choose to not present them as behavioral modification options at all."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f96bb07_9fb353e9","line":162,"range":{"start_line":162,"start_character":26,"end_line":162,"end_character":47},"updated":"2018-01-18 15:20:32.000000000","message":"s/ a //","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":181,"context_line":"  information, such as microversion ranges. Using"},{"line_number":182,"context_line":"  ``{fetch-version-information}`` allows them to request that the version"},{"line_number":183,"context_line":"  document be fetched even when an optimization in the process would otherwise"},{"line_number":184,"context_line":"  allow fetching the document to be skipped. Defaults to False."},{"line_number":185,"context_line":""},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"Discovery Results"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_6202f671","line":184,"updated":"2017-10-05 13:11:18.000000000","message":"Maybe it\u0027s only me, but I don\u0027t find this option particularly practical. With the microversions taking over the world, it is essential to know the range of versions you work with. And as we don\u0027t encode microversions in the URLs (a bit mistake, if you ask me, but okay), it will be always required for fetch version information anyway, no?","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":181,"context_line":"  information, such as microversion ranges. Using"},{"line_number":182,"context_line":"  ``{fetch-version-information}`` allows them to request that the version"},{"line_number":183,"context_line":"  document be fetched even when an optimization in the process would otherwise"},{"line_number":184,"context_line":"  allow fetching the document to be skipped. Defaults to False."},{"line_number":185,"context_line":""},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"Discovery Results"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_a96c4e08","line":184,"in_reply_to":"7f515b1d_6202f671","updated":"2017-10-05 16:28:48.000000000","message":"No - there are plenty of clouds that do not have new enough services to have microversions, and there are plenty of services that don\u0027t have them yet. There are also users who do not need to do any microversion interaction for their application (I\u0027m one of those at the moment) - and where the extra fetch to get the microversion range would be wasted.\n\nThis is implemented in keystoneauth but is mostly hidden from the user - it depends on which methods you call. For instance - session.get_endpoint() does not do a microversion fetch if it doens\u0027t otherwise need to to find the proper major version because it would discard the information before returning it. However, session.get_endpoint_data() (which will return metainfo about the endpoint including microversion info) will trigger an additional fetch to get microversion info even if the major version matches because it\u0027s necessary to provide the data.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0a1490f4a48a3a43e1a6d44ffe47e7f57e47e9ba","unresolved":false,"context_lines":[{"line_number":181,"context_line":"  information, such as microversion ranges. Using"},{"line_number":182,"context_line":"  ``{fetch-version-information}`` allows them to request that the version"},{"line_number":183,"context_line":"  document be fetched even when an optimization in the process would otherwise"},{"line_number":184,"context_line":"  allow fetching the document to be skipped. Defaults to False."},{"line_number":185,"context_line":""},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"Discovery Results"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f96bb07_7f5a0783","line":184,"in_reply_to":"7f515b1d_a96c4e08","updated":"2018-01-18 15:20:32.000000000","message":"Perhaps add some wording to explain that (and why) this isn\u0027t needed for services that implement microversions.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":198,"context_line":""},{"line_number":199,"context_line":"max-version"},{"line_number":200,"context_line":"  If the service supports microversions, what is the maximum microversion the"},{"line_number":201,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":202,"context_line":""},{"line_number":203,"context_line":"min-version"},{"line_number":204,"context_line":"  If the service supports microversions, what is the minimum microversion the"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_42f93a7e","line":201,"updated":"2017-10-05 13:11:18.000000000","message":"How should omitted be treated by the caller? Does it mean that the project does not support microversions? Can we assume that if max-version is None, min-version is also None?","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":198,"context_line":""},{"line_number":199,"context_line":"max-version"},{"line_number":200,"context_line":"  If the service supports microversions, what is the maximum microversion the"},{"line_number":201,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":202,"context_line":""},{"line_number":203,"context_line":"min-version"},{"line_number":204,"context_line":"  If the service supports microversions, what is the minimum microversion the"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_893d12df","line":201,"in_reply_to":"7f515b1d_42f93a7e","updated":"2017-10-05 16:28:48.000000000","message":"Yes - omitted/None means the service doesn\u0027t have microversions.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":9,"context_line":""},{"line_number":10,"context_line":".. note:: The process described in this document is compatible with all known"},{"line_number":11,"context_line":"          OpenStack Public Clouds and also matches the behavior of the python"},{"line_number":12,"context_line":"          library keystoneauth, which is the reference implementation of"},{"line_number":13,"context_line":"          authenticating with keystone and consuming information from the"},{"line_number":14,"context_line":"          catalog. In some places an argument can be made for a different"},{"line_number":15,"context_line":"          process, but given keystoneauth\u0027s wide use and reference nature,"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bb3e5c88","line":12,"range":{"start_line":12,"start_character":18,"end_line":12,"end_character":30},"updated":"2019-03-28 16:33:17.000000000","message":"link (at least the first time)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":27,"context_line":"User Request"},{"line_number":28,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":".. note:: It is worth noting that \u0027user\u0027 is a maleable concept. For instance,"},{"line_number":31,"context_line":"          the shade library performs service discovery on behalf of its users"},{"line_number":32,"context_line":"          so does not expect its users to provide a \u0027service-type\u0027. In that"},{"line_number":33,"context_line":"          case, shade is the \u0027user\u0027 of the keystoneauth library which is the"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_1b3c5091","line":30,"range":{"start_line":30,"start_character":46,"end_line":30,"end_character":54},"updated":"2019-03-28 16:33:17.000000000","message":"malleable","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":39,"context_line":"knowing some number of these parameters. Each additional input expected from"},{"line_number":40,"context_line":"the user without an answer of \"where do they learn this information\" will"},{"line_number":41,"context_line":"increase the difficulty of a user consuming services, so client libraries and"},{"line_number":42,"context_line":"utilities are strongly encouraged to do whatever they can to be extra helpful"},{"line_number":43,"context_line":"in helping the user ask the right question."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":".. note:: Be liberal with what you accept and strict with what you emit."},{"line_number":46,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_fb0624ce","line":43,"range":{"start_line":42,"start_character":37,"end_line":43,"end_character":10},"updated":"2019-03-28 16:33:17.000000000","message":"\"do whatever they can\", \"to be extra helpful\", and \"in helping\" are all pretty much the same thing. Consider reducing. (This document is big enough, we don\u0027t need any extra additional redundancy (see what I did there?).)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":42,"context_line":"utilities are strongly encouraged to do whatever they can to be extra helpful"},{"line_number":43,"context_line":"in helping the user ask the right question."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":".. note:: Be liberal with what you accept and strict with what you emit."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"The following is a list of such pieces of information that can be provided"},{"line_number":48,"context_line":"as user input. When an implementation exposes the ability for a user to"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9bf5a0cd","line":45,"range":{"start_line":45,"start_character":0,"end_line":45,"end_character":72},"updated":"2019-03-28 16:33:17.000000000","message":"While pithy and one of my favorite aphorisms, I\u0027m not sure this adds anything here.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":78,"context_line":"  The region of the service the user desires to work with. May be optional,"},{"line_number":79,"context_line":"  depending on whether the cloud has more than one region. Services"},{"line_number":80,"context_line":"  all exist within regions, but some clouds only have one region."},{"line_number":81,"context_line":"  If ``{be-strict}`` (see below) has been given, ``{region-name}`` is required."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"  .. note:: It is highly recommended that ``{region-name}`` always be required"},{"line_number":84,"context_line":"            to protect against single-region clouds adding a region in the"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_1b33f0ac","line":81,"range":{"start_line":81,"start_character":5,"end_line":81,"end_character":32},"updated":"2019-03-28 16:33:17.000000000","message":"or just link to it","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":83,"context_line":"  .. note:: It is highly recommended that ``{region-name}`` always be required"},{"line_number":84,"context_line":"            to protect against single-region clouds adding a region in the"},{"line_number":85,"context_line":"            future. However, the canonical OpenStack implementation"},{"line_number":86,"context_line":"            *keystoneauth* today allows region name to be omitted and there are"},{"line_number":87,"context_line":"            a large number of clouds in existence with a single region named"},{"line_number":88,"context_line":"            ``RegionOne``.  For completely new libraries or major versions"},{"line_number":89,"context_line":"            where breaking behavior is acceptable, requiring region name"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bb25fc5d","line":86,"range":{"start_line":86,"start_character":12,"end_line":86,"end_character":26},"updated":"2019-03-28 16:33:17.000000000","message":"consistency of emphasis (previous references to keystoneauth are undecorated)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"f0c81587cf968b45794f5ce952a1c9f2ab486b08","unresolved":false,"context_lines":[{"line_number":85,"context_line":"            future. However, the canonical OpenStack implementation"},{"line_number":86,"context_line":"            *keystoneauth* today allows region name to be omitted and there are"},{"line_number":87,"context_line":"            a large number of clouds in existence with a single region named"},{"line_number":88,"context_line":"            ``RegionOne``.  For completely new libraries or major versions"},{"line_number":89,"context_line":"            where breaking behavior is acceptable, requiring region name"},{"line_number":90,"context_line":"            by default would be preferred, but breaking users just to introduce"},{"line_number":91,"context_line":"            the restriction is discouraged."}],"source_content_type":"text/x-rst","patch_set":29,"id":"9fdfeff1_8c41fba8","line":88,"range":{"start_line":88,"start_character":26,"end_line":88,"end_character":28},"updated":"2019-02-14 23:33:11.000000000","message":"2 spaces! Ack!!","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":91,"context_line":"            the restriction is discouraged."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"``interface``"},{"line_number":94,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin``, that"},{"line_number":95,"context_line":"  the user wants to use. A user should be able to request a list of interfaces"},{"line_number":96,"context_line":"  they find acceptable in the order of their preference, such as"},{"line_number":97,"context_line":"  ``[\u0027internal\u0027, \u0027public\u0027]`` (Optional, defaults to ``public``)"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9b1e000a","line":94,"range":{"start_line":94,"start_character":23,"end_line":94,"end_character":30},"updated":"2019-03-28 16:33:17.000000000","message":"Isn\u0027t it exactly these three? Or is that just in ksa?\n\n[Later] I guess there\u0027s *URL as well.\n\nIMO this would read fine as:\n\n\"Which API interface (``public``, ``internal``, or ``admin``) the user wants to use.\"","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"f0c81587cf968b45794f5ce952a1c9f2ab486b08","unresolved":false,"context_lines":[{"line_number":99,"context_line":"``endpoint-version`` OR ``min-endpoint-version``, ``max-endpoint-version``"},{"line_number":100,"context_line":"  The **major** version of the service the user desires to work with. Optional."},{"line_number":101,"context_line":""},{"line_number":102,"context_line":"  An endpoint version is inherently a range with a minimum and a maximum value."},{"line_number":103,"context_line":"  Whether it is presented to the user as a single parameter or a pair of"},{"line_number":104,"context_line":"  parameters is an implementation detail."},{"line_number":105,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"9fdfeff1_ac6e3f2c","line":102,"range":{"start_line":102,"start_character":13,"end_line":102,"end_character":14},"updated":"2019-02-14 23:33:11.000000000","message":"I would leave the hyphen there, since you are referring to the name of the filter.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"7de312b7be12497a024fbaef697844f532f2e9cb","unresolved":false,"context_lines":[{"line_number":112,"context_line":"               No services currently use both major versions and microversions"},{"line_number":113,"context_line":"               in the form of ``X.Y``."},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"  .. TODO(dtantsur): so, what if a service has both major versions in the form"},{"line_number":116,"context_line":"                     of ``X.Y`` and microversions?"},{"line_number":117,"context_line":""},{"line_number":118,"context_line":"  Version strings are not decimals, the are a tuple of 2 numbers combined with"},{"line_number":119,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"3f79a3b5_eb18bccd","line":116,"range":{"start_line":115,"start_character":0,"end_line":116,"end_character":50},"updated":"2019-05-17 12:29:27.000000000","message":"we throw our hands in the air and scream","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":119,"context_line":"  a dot. Therefore, ``3.10`` is higher than ``3.9``."},{"line_number":120,"context_line":""},{"line_number":121,"context_line":"  A user can omit the endpoint-version indicating that they want to use"},{"line_number":122,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":123,"context_line":""},{"line_number":124,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":125,"context_line":"  case the ``{endpoint-version}`` should be ``latest``. If s"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_5b1418e9","line":122,"range":{"start_line":122,"start_character":30,"end_line":122,"end_character":51},"updated":"2019-03-28 16:33:17.000000000","message":"Is it really ``{service-catalog}`` or is it just service catalog? As decorated, I went looking for its definition as a keyword or whatever (and didn\u0027t find it). If appropriate, perhaps `service catalog`_ (i.e. a link to the doc describing what it is and/or how to set it up and/or how to consume it (um, which is this document, right?)). But ``{service-catalog}`` is misleading IMO.\n\n[Later] Oh, it makes more sense in light of L264. Even so, I\u0027m thinking this and all references before that point should just be undecorated and unhyphenated.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"7de312b7be12497a024fbaef697844f532f2e9cb","unresolved":false,"context_lines":[{"line_number":122,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":123,"context_line":""},{"line_number":124,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":125,"context_line":"  case the ``{endpoint-version}`` should be ``latest``. If s"},{"line_number":126,"context_line":"  ``{min-endpoint-version}`` is ``latest``, ``{max-endpoint-version}`` must be"},{"line_number":127,"context_line":"  omitted or also ``latest``."},{"line_number":128,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"3f79a3b5_eb6d1c2f","line":125,"range":{"start_line":125,"start_character":59,"end_line":125,"end_character":60},"updated":"2019-05-17 12:29:27.000000000","message":"rogue letter!","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":122,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":123,"context_line":""},{"line_number":124,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":125,"context_line":"  case the ``{endpoint-version}`` should be ``latest``. If s"},{"line_number":126,"context_line":"  ``{min-endpoint-version}`` is ``latest``, ``{max-endpoint-version}`` must be"},{"line_number":127,"context_line":"  omitted or also ``latest``."},{"line_number":128,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_3b758c32","line":125,"range":{"start_line":125,"start_character":59,"end_line":125,"end_character":60},"updated":"2019-03-28 16:33:17.000000000","message":"strike?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":124,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":125,"context_line":"  case the ``{endpoint-version}`` should be ``latest``. If s"},{"line_number":126,"context_line":"  ``{min-endpoint-version}`` is ``latest``, ``{max-endpoint-version}`` must be"},{"line_number":127,"context_line":"  omitted or also ``latest``."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":"  A version can be specified with a minor value of ``latest`` to indicate"},{"line_number":130,"context_line":"  the highest minor version of a given major version. For instance,"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bb965c3d","line":127,"range":{"start_line":127,"start_character":13,"end_line":127,"end_character":17},"updated":"2019-03-28 16:33:17.000000000","message":"also be","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":153,"context_line":"  Arbitrary name given to the service by the deployer. Optional."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"  .. note:: In all except the most extreme cases this should never be needed"},{"line_number":156,"context_line":"            and its use as a meaningful identifier by Deployers is strongly"},{"line_number":157,"context_line":"            discouraged. However, the Consumer has no way to otherwise mitigate"},{"line_number":158,"context_line":"            the situation if their Deployer has provided them with a catalog"},{"line_number":159,"context_line":"            where a ``service-name`` must be used, so ``service-name`` must be"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bbaf3c7b","line":156,"range":{"start_line":156,"start_character":54,"end_line":156,"end_character":63},"updated":"2019-03-28 16:33:17.000000000","message":"why is this capitalized here?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":154,"context_line":""},{"line_number":155,"context_line":"  .. note:: In all except the most extreme cases this should never be needed"},{"line_number":156,"context_line":"            and its use as a meaningful identifier by Deployers is strongly"},{"line_number":157,"context_line":"            discouraged. However, the Consumer has no way to otherwise mitigate"},{"line_number":158,"context_line":"            the situation if their Deployer has provided them with a catalog"},{"line_number":159,"context_line":"            where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":160,"context_line":"            accepted as input."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_dbb248e5","line":157,"range":{"start_line":157,"start_character":38,"end_line":157,"end_character":46},"updated":"2019-03-28 16:33:17.000000000","message":"ditto","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":155,"context_line":"  .. note:: In all except the most extreme cases this should never be needed"},{"line_number":156,"context_line":"            and its use as a meaningful identifier by Deployers is strongly"},{"line_number":157,"context_line":"            discouraged. However, the Consumer has no way to otherwise mitigate"},{"line_number":158,"context_line":"            the situation if their Deployer has provided them with a catalog"},{"line_number":159,"context_line":"            where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":160,"context_line":"            accepted as input."},{"line_number":161,"context_line":"            If ``{be-strict}`` (see below) has been requested, a user supplying"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_7bcd5464","line":158,"range":{"start_line":158,"start_character":35,"end_line":158,"end_character":43},"updated":"2019-03-28 16:33:17.000000000","message":"ditto","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":158,"context_line":"            the situation if their Deployer has provided them with a catalog"},{"line_number":159,"context_line":"            where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":160,"context_line":"            accepted as input."},{"line_number":161,"context_line":"            If ``{be-strict}`` (see below) has been requested, a user supplying"},{"line_number":162,"context_line":"            ``{service-name}`` should be an error."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"``service-id``"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9bc84055","line":161,"range":{"start_line":161,"start_character":15,"end_line":161,"end_character":42},"updated":"2019-03-28 16:33:17.000000000","message":"link (as above)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":158,"context_line":"            the situation if their Deployer has provided them with a catalog"},{"line_number":159,"context_line":"            where a ``service-name`` must be used, so ``service-name`` must be"},{"line_number":160,"context_line":"            accepted as input."},{"line_number":161,"context_line":"            If ``{be-strict}`` (see below) has been requested, a user supplying"},{"line_number":162,"context_line":"            ``{service-name}`` should be an error."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"``service-id``"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_5bbe58ae","line":161,"range":{"start_line":161,"start_character":63,"end_line":161,"end_character":70},"updated":"2019-03-28 16:33:17.000000000","message":"strike (else it sounds like the user is an error)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":165,"context_line":"  Unique identifier for an endpoint in the catalog. Optional."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"  .. note:: On clouds with well-formed catalogs ``service-id`` should never be"},{"line_number":168,"context_line":"            needed. If ``{be-strict}`` has been requested, supplying"},{"line_number":169,"context_line":"            ``{service-id}`` should be an error."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"``endpoint-override``"},{"line_number":172,"context_line":"  An endpoint for the service that the user has procured from some other"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_fbde240f","line":169,"range":{"start_line":168,"start_character":59,"end_line":169,"end_character":48},"updated":"2019-03-28 16:33:17.000000000","message":"like this","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":169,"context_line":"            ``{service-id}`` should be an error."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"``endpoint-override``"},{"line_number":172,"context_line":"  An endpoint for the service that the user has procured from some other"},{"line_number":173,"context_line":"  source. (Optional, defaults to omitted.)"},{"line_number":174,"context_line":""},{"line_number":175,"context_line":"Discovery Behavior Modifiers"},{"line_number":176,"context_line":"----------------------------"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_dbe7a8e2","line":173,"range":{"start_line":172,"start_character":62,"end_line":173,"end_character":8},"updated":"2019-03-28 16:33:17.000000000","message":"some source other than the service catalog","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":210,"context_line":"* The actual values found for all of the input values above."},{"line_number":211,"context_line":""},{"line_number":212,"context_line":"  Found values will be referred to in these documents as ``found-{value}`` to"},{"line_number":213,"context_line":"  differentiate. So if a user requested an ``{endpoint-version}`` of"},{"line_number":214,"context_line":"  ``latest``, ``{found-endpoint-version}`` might be ``3.5``."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"* ``service-endpoint``"},{"line_number":217,"context_line":"  The endpoint to use as the root of the service."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9bf6008f","line":214,"range":{"start_line":213,"start_character":17,"end_line":214,"end_character":60},"updated":"2019-03-28 16:33:17.000000000","message":"great example","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":218,"context_line":""},{"line_number":219,"context_line":"* ``max-version``"},{"line_number":220,"context_line":"  If the service supports microversions, what is the maximum microversion the"},{"line_number":221,"context_line":"  service supports. Optional, defaults to omitted, which implies that"},{"line_number":222,"context_line":"  microversions are not supported."},{"line_number":223,"context_line":""},{"line_number":224,"context_line":"* ``min-version``"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_db356846","line":221,"range":{"start_line":221,"start_character":20,"end_line":221,"end_character":56},"updated":"2019-03-28 16:33:17.000000000","message":"this is weird wording for an output, suggest \"If absent, implies...\"","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":223,"context_line":""},{"line_number":224,"context_line":"* ``min-version``"},{"line_number":225,"context_line":"  If the service supports microversions, what is the minimum microversion the"},{"line_number":226,"context_line":"  service supports. Optional, defaults to omitted, which implies that"},{"line_number":227,"context_line":"  microversions are not supported."},{"line_number":228,"context_line":""},{"line_number":229,"context_line":"If the process was unsuccessful, an error should be returned explaining which"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_3b46ecc1","line":226,"range":{"start_line":226,"start_character":20,"end_line":226,"end_character":57},"updated":"2019-03-28 16:33:17.000000000","message":"ditto","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":229,"context_line":"If the process was unsuccessful, an error should be returned explaining which"},{"line_number":230,"context_line":"part failed. For instance, was a matching service not found at all or was"},{"line_number":231,"context_line":"a matching version not found. If a matching version was not found, the error"},{"line_number":232,"context_line":"should contain a list of version that were found."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"In the description that follows, each of the above inputs and outputs will"},{"line_number":235,"context_line":"be referred to like ``{endpoint-override}`` so that it is clear whether a user"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bb0bbc7a","line":232,"range":{"start_line":232,"start_character":25,"end_line":232,"end_character":32},"updated":"2019-03-28 16:33:17.000000000","message":"versions","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":231,"context_line":"a matching version not found. If a matching version was not found, the error"},{"line_number":232,"context_line":"should contain a list of version that were found."},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"In the description that follows, each of the above inputs and outputs will"},{"line_number":235,"context_line":"be referred to like ``{endpoint-override}`` so that it is clear whether a user"},{"line_number":236,"context_line":"supplied input to the process or one of the expected outputs is being"},{"line_number":237,"context_line":"discussed. Other values that are fetched at one point in the process and"},{"line_number":238,"context_line":"referred to at a later point are similarly referred to like"},{"line_number":239,"context_line":"``{service-catalog}``. Names will not be reused within the process to"},{"line_number":240,"context_line":"hold different content at different times."},{"line_number":241,"context_line":""},{"line_number":242,"context_line":"Discovery Algorithm"},{"line_number":243,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9b24c00e","line":240,"range":{"start_line":234,"start_character":0,"end_line":240,"end_character":42},"updated":"2019-03-28 16:33:17.000000000","message":"This paragraph is redundant at best, but probably just confusing. You\u0027ve already established the ``{...}`` convention and described the found-* business. I can\u0027t tell what this is trying to add.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":263,"context_line":"#. Authenticate to keystone at the ``{auth-url}``, retreiving a ``token``"},{"line_number":264,"context_line":"   which contains the ``{service-catalog}``."},{"line_number":265,"context_line":""},{"line_number":266,"context_line":"   .. note:: This step is obviously skipped for clouds without authentication."},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"#. If the user has provided ``{endpoint-override}``, it is used as"},{"line_number":269,"context_line":"   ``{catalog-endpoint}``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_5b8bb8be","line":266,"range":{"start_line":266,"start_character":3,"end_line":266,"end_character":78},"updated":"2019-03-28 16:33:17.000000000","message":"um, okay, so how do you get a ``{service-catalog}`` in that case?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":277,"context_line":"   and find the suitable ``{service-endpoint}`` using the version discovery"},{"line_number":278,"context_line":"   procedure from :doc:`consuming-catalog/version-discovery`."},{"line_number":279,"context_line":""},{"line_number":280,"context_line":"Table of Contents"},{"line_number":281,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":282,"context_line":""},{"line_number":283,"context_line":".. toctree::"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"   consuming-catalog/endpoint"},{"line_number":286,"context_line":"   consuming-catalog/version-discovery"},{"line_number":287,"context_line":"   consuming-catalog/authority"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_bb9c1c0e","line":287,"range":{"start_line":280,"start_character":0,"end_line":287,"end_character":30},"updated":"2019-03-28 16:33:17.000000000","message":"odd that this is at the bottom of the page...","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b90e479d7ed194fd6ce35633277a0ffd1f994626","unresolved":false,"context_lines":[{"line_number":256,"context_line":"from https://service-types.openstack.org/service-types.json and potentially"},{"line_number":257,"context_line":"cache it. It is recommended that client libraries handle consumption of the"},{"line_number":258,"context_line":"historical data for their users but also allow some mechanism for the user to"},{"line_number":259,"context_line":"provide a more up to date verison of the data if necessary."},{"line_number":260,"context_line":""},{"line_number":261,"context_line":"The basic process is:"},{"line_number":262,"context_line":""}],"source_content_type":"text/x-rst","patch_set":33,"id":"ff570b3c_5d9b9d71","line":259,"updated":"2020-06-02 19:59:38.000000000","message":"s/verison/version/","commit_id":"e8095800887e05857056707698a35452fbba3df8"}],"guidelines/consuming-catalog/authority.rst":[{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":32,"context_line":"#. The current version of the JSON file should always be the preferred file to"},{"line_number":33,"context_line":"   use."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"#. The JSON file is similar to timezone data. It should not be considered"},{"line_number":36,"context_line":"   versioned such that stable releases of distros should provide a"},{"line_number":37,"context_line":"   frozen version of it. Distro packages should instead update for all"},{"line_number":38,"context_line":"   active releases when a new version of the file is published."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_5b52d836","line":35,"range":{"start_line":35,"start_character":3,"end_line":35,"end_character":45},"updated":"2019-03-28 16:33:17.000000000","message":"I don\u0027t get this analogy. Could we do without this sentence?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"}],"guidelines/consuming-catalog/endpoint.rst":[{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":33,"context_line":"two main keys that concern discovery:"},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"``type``"},{"line_number":36,"context_line":"  Matches ``{service-type}``"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"``endpoints``"},{"line_number":39,"context_line":"  List of endpoint objects for that service"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_1b369004","line":36,"range":{"start_line":36,"start_character":10,"end_line":36,"end_character":28},"updated":"2019-03-28 16:33:17.000000000","message":"this (and its analogs below) could be links back to their definitions in consuming-catalog.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":51,"context_line":"was used. For both versions each endpoint object has a ``region`` key,"},{"line_number":52,"context_line":"which should match ``{region-name}`` if one was given."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"In v2 auth the endpoint object has three keys ``publicURL``,"},{"line_number":55,"context_line":"``internalURL``, ``adminURL``. The endpoint for the ``{interface}`` requested"},{"line_number":56,"context_line":"by the user is found in the key with the name matching ``{interface}`` plus"},{"line_number":57,"context_line":"the string ``URL``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_9b2120b7","line":54,"range":{"start_line":54,"start_character":45,"end_line":54,"end_character":46},"updated":"2019-03-28 16:33:17.000000000","message":":","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":126,"context_line":"----------------------------"},{"line_number":127,"context_line":""},{"line_number":128,"context_line":"#. If ``{endpoint-version}`` was given and ``{service-type}`` ends with a"},{"line_number":129,"context_line":"   suffix of ``v[0-9]+$`` and ``{endpoint-version}`` does not match that suffix"},{"line_number":130,"context_line":"   (see `Comparing Major Versions`_), STOP. Return an error that the user"},{"line_number":131,"context_line":"   has requested a versioned ``{service-type}`` alias and an incompatible"},{"line_number":132,"context_line":"   ``{endpoint-version}``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_5b009802","line":129,"range":{"start_line":129,"start_character":13,"end_line":129,"end_character":25},"updated":"2019-03-28 16:33:17.000000000","message":"technically ``v[1-9][0-9]*$`` (please don\u0027t change this)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":128,"context_line":"#. If ``{endpoint-version}`` was given and ``{service-type}`` ends with a"},{"line_number":129,"context_line":"   suffix of ``v[0-9]+$`` and ``{endpoint-version}`` does not match that suffix"},{"line_number":130,"context_line":"   (see `Comparing Major Versions`_), STOP. Return an error that the user"},{"line_number":131,"context_line":"   has requested a versioned ``{service-type}`` alias and an incompatible"},{"line_number":132,"context_line":"   ``{endpoint-version}``."},{"line_number":133,"context_line":""},{"line_number":134,"context_line":"#. Find the objects in the ``{service-catalog}`` that match the requested"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_76148b44","line":131,"range":{"start_line":131,"start_character":48,"end_line":131,"end_character":53},"updated":"2019-03-28 16:33:17.000000000","message":"strike?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":141,"context_line":"             ``{be-strict}`` was not requested and the catalog does not have a"},{"line_number":142,"context_line":"             ``name`` field, ``{service-name}`` should be ignored."},{"line_number":143,"context_line":""},{"line_number":144,"context_line":"#. If ``{service-id}`` was given and the objects remaining have a ``id``"},{"line_number":145,"context_line":"   field, keep only the ones where ``id`` matches ``{service-id}``."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"   .. note:: Catalogs from Keystone v2 do not have an id field. If"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_963817d3","line":144,"range":{"start_line":144,"start_character":64,"end_line":144,"end_character":65},"updated":"2019-03-28 16:33:17.000000000","message":"an","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":144,"context_line":"#. If ``{service-id}`` was given and the objects remaining have a ``id``"},{"line_number":145,"context_line":"   field, keep only the ones where ``id`` matches ``{service-id}``."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"   .. note:: Catalogs from Keystone v2 do not have an id field. If"},{"line_number":148,"context_line":"             ``{be-strict}`` was not requested and the catalog does not have a"},{"line_number":149,"context_line":"             ``id`` field, ``{service-id}`` should be ignored."},{"line_number":150,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_363363f8","line":147,"range":{"start_line":147,"start_character":54,"end_line":147,"end_character":56},"updated":"2019-03-28 16:33:17.000000000","message":"``id``","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":150,"context_line":""},{"line_number":151,"context_line":"The list of remaining objects are the ``{candidate-catalog-objects}``. If this"},{"line_number":152,"context_line":"list is empty, return an error that there are no endpoints matching"},{"line_number":153,"context_line":"``{service-type}`` and ``{service-name}``."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"#. Use ``{candidate-catalog-objects}`` to produce the list of"},{"line_number":156,"context_line":"   ``{candidate-endpoints}``. For each endpoint object in each of the"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_562e2f8c","line":153,"range":{"start_line":153,"start_character":19,"end_line":153,"end_character":22},"updated":"2019-03-28 16:33:17.000000000","message":"and/or","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":150,"context_line":""},{"line_number":151,"context_line":"The list of remaining objects are the ``{candidate-catalog-objects}``. If this"},{"line_number":152,"context_line":"list is empty, return an error that there are no endpoints matching"},{"line_number":153,"context_line":"``{service-type}`` and ``{service-name}``."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"#. Use ``{candidate-catalog-objects}`` to produce the list of"},{"line_number":156,"context_line":"   ``{candidate-endpoints}``. For each endpoint object in each of the"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_f64e3b6d","line":153,"range":{"start_line":153,"start_character":41,"end_line":153,"end_character":42},"updated":"2019-03-28 16:33:17.000000000","message":"and/or ``{service-id}``","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":152,"context_line":"list is empty, return an error that there are no endpoints matching"},{"line_number":153,"context_line":"``{service-type}`` and ``{service-name}``."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"#. Use ``{candidate-catalog-objects}`` to produce the list of"},{"line_number":156,"context_line":"   ``{candidate-endpoints}``. For each endpoint object in each of the"},{"line_number":157,"context_line":"   ``{candidate-catalog-objects}``:"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_f6771b9f","line":155,"range":{"start_line":155,"start_character":0,"end_line":155,"end_character":2},"updated":"2019-03-28 16:33:17.000000000","message":"Numbering starts over here. It looks okay, but perhaps the intent was to have continuity? If so, I think that would be possible by indenting the previous paragraph, but then it would look like it was part of the previous number, which I don\u0027t think it is. Stephen may have a better suggestion.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":157,"context_line":"   ``{candidate-catalog-objects}``:"},{"line_number":158,"context_line":""},{"line_number":159,"context_line":"   #. If v2, if there is no key of the form ``{interface}URL`` for any of the"},{"line_number":160,"context_line":"      the ``{interface}`` values given, discard the endpoint."},{"line_number":161,"context_line":""},{"line_number":162,"context_line":"   #. If v3, if ``interface`` does not match any of the ``{interface}`` values"},{"line_number":163,"context_line":"      given, discard the endpoint."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_b66d13cd","line":160,"range":{"start_line":160,"start_character":6,"end_line":160,"end_character":9},"updated":"2019-03-28 16:33:17.000000000","message":"strike","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":170,"context_line":"   ``{region_name}`` was given and does not match either of ``region`` or"},{"line_number":171,"context_line":"   ``region_id``, discard the endpoint."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"   If there are no remaining endpoints, return an error that there are no"},{"line_number":174,"context_line":"   endpoints matching ``{region_name}``, preferrably including the list of"},{"line_number":175,"context_line":"   regions that were found."},{"line_number":176,"context_line":""},{"line_number":177,"context_line":"#. From the set of remaining candidate endpoints, find the ones that best"},{"line_number":178,"context_line":"   matches the requested ``{service-type}`` (see `Find Endpoint Matching Best"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_366123d4","line":175,"range":{"start_line":173,"start_character":3,"end_line":175,"end_character":27},"updated":"2019-03-28 16:33:17.000000000","message":"The equivalent sentence at L165-7 was numbered; either both or neither should be.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":178,"context_line":"   matches the requested ``{service-type}`` (see `Find Endpoint Matching Best"},{"line_number":179,"context_line":"   Service Type`_)."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"#. From the set of remaining candidate endpoints, find the ones that best"},{"line_number":182,"context_line":"   matches the best available requested ``{interface}``: in order of"},{"line_number":183,"context_line":"   preference of the ``{interface}`` list, return all endpoints that match"},{"line_number":184,"context_line":"   the first ``{interface}`` that has any matching endpoints."},{"line_number":185,"context_line":""},{"line_number":186,"context_line":"The remaining ``{candidate-endpoints}`` match the request. If there is more"},{"line_number":187,"context_line":"than one of them, use the first, but emit a warning to the user that more"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_568aaf63","line":184,"range":{"start_line":181,"start_character":59,"end_line":184,"end_character":61},"updated":"2019-03-28 16:33:17.000000000","message":"This is kind of garbled.\n\n\"...find the first ones that match the requested ``{interface}`` list in sequential order of preference.\"\n\nUgh, that\u0027s not a whole lot better. Let me think about this some more.\n\n[Later] How about:\n\n\"Apply the requested ``{interface}`` filter to the set of remaining candidate endpoints. If ``{interface}`` is a list, process it in order, stopping as soon as any endpoints match.\"","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":215,"context_line":"   :doc:`OpenStack Service Types Authority \u003cauthority\u003e` and the entry\u0027s type"},{"line_number":216,"context_line":"   matches the official type, it is a candidate."},{"line_number":217,"context_line":""},{"line_number":218,"context_line":"#. If the requested type is an alias of an official type from the"},{"line_number":219,"context_line":"   :doc:`OpenStack Service Types Authority \u003cauthority\u003e` that has aliases and"},{"line_number":220,"context_line":"   the entry\u0027s type matches one of the aliases and ``{endpoint-version}`` was"},{"line_number":221,"context_line":"   given and the found alias ends with a suffix of ``v[0-9]+$`` and"},{"line_number":222,"context_line":"   ``{endpoint-version}`` matches the version in the suffix (see `Comparing"},{"line_number":223,"context_line":"   Major Versions`_) it is a candidate."},{"line_number":224,"context_line":""},{"line_number":225,"context_line":"Find Endpoint Matching Best Service Type"},{"line_number":226,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_b69665ef","line":223,"range":{"start_line":218,"start_character":3,"end_line":223,"end_character":39},"updated":"2019-03-28 16:33:17.000000000","message":"ye gods","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":233,"context_line":"#. If the requested ``{service-type}``"},{"line_number":234,"context_line":""},{"line_number":235,"context_line":"   * is an official type from the :doc:`OpenStack Service Types Authority"},{"line_number":236,"context_line":"     \u003cauthority\u003e` that has aliases"},{"line_number":237,"context_line":"   * ``{endpoint-version}`` was given"},{"line_number":238,"context_line":""},{"line_number":239,"context_line":"   Look for aliases that end with a version suffix of the form ``v[0-9]+$``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_168bb9bf","line":236,"updated":"2019-03-28 16:33:17.000000000","message":"; and","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":244,"context_line":"#. If the requested ``{service-type}``"},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"   * is an official type in the :doc:`OpenStack Service Types Authority"},{"line_number":247,"context_line":"     \u003cauthority\u003e` that has aliases"},{"line_number":248,"context_line":"   * ``{endpoint-version}`` was not given"},{"line_number":249,"context_line":""},{"line_number":250,"context_line":"   check each alias in the order listed to see if it has a matching endpoint"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_56ae212e","line":247,"updated":"2019-03-28 16:33:17.000000000","message":"; and","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":254,"context_line":"#. If the requested ``{service-type}``"},{"line_number":255,"context_line":""},{"line_number":256,"context_line":"   * is an alias of an official type in the"},{"line_number":257,"context_line":"     :doc:`OpenStack Service Types Authority \u003cauthority\u003e`"},{"line_number":258,"context_line":"   * ``{endpoint-version}`` was given"},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"   look for aliases that end with a version suffix of the form ``v[0-9]+$``. If"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_367835c2","line":257,"updated":"2019-03-28 16:33:17.000000000","message":"; and","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":304,"context_line":"   to the first value and less than or equal to the second value is a match."},{"line_number":305,"context_line":"   Equality is judged by the above rules. Greater than and less than are judged"},{"line_number":306,"context_line":"   as expected: first by comparing the first number, and if those match then by"},{"line_number":307,"context_line":"   comparing the second number.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":308,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":309,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."},{"line_number":310,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_7611dd5c","line":307,"range":{"start_line":307,"start_character":59,"end_line":307,"end_character":66},"updated":"2019-03-28 16:33:17.000000000","message":"suggest adding a space after this comma","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":305,"context_line":"   Equality is judged by the above rules. Greater than and less than are judged"},{"line_number":306,"context_line":"   as expected: first by comparing the first number, and if those match then by"},{"line_number":307,"context_line":"   comparing the second number.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":308,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":309,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."},{"line_number":310,"context_line":""},{"line_number":311,"context_line":"#. If ``required`` is a range without a maximum value, maximum should be"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_560aa125","line":308,"range":{"start_line":308,"start_character":65,"end_line":308,"end_character":76},"updated":"2019-03-28 16:33:17.000000000","message":"ditto","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":306,"context_line":"   as expected: first by comparing the first number, and if those match then by"},{"line_number":307,"context_line":"   comparing the second number.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":308,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":309,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."},{"line_number":310,"context_line":""},{"line_number":311,"context_line":"#. If ``required`` is a range without a maximum value, maximum should be"},{"line_number":312,"context_line":"   treated as if it is ``latest``."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_d12c5b9a","line":309,"range":{"start_line":309,"start_character":37,"end_line":309,"end_character":44},"updated":"2019-03-28 16:33:17.000000000","message":"eh? If ``{required}`` max is 4.0, how does 4.7 match?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":352,"context_line":""},{"line_number":353,"context_line":"::"},{"line_number":354,"context_line":""},{"line_number":355,"context_line":"  service_type \u003d \u0027block-storage\u0027"},{"line_number":356,"context_line":"  # block-storage is not found, get list of aliases"},{"line_number":357,"context_line":"  # volumev3 is found, return it"},{"line_number":358,"context_line":""},{"line_number":359,"context_line":"  service_type \u003d \u0027volumev2\u0027"},{"line_number":360,"context_line":"  # volumev2 not an official type in authority, but is in catalog"},{"line_number":361,"context_line":"  # return volumev2 entry"},{"line_number":362,"context_line":""},{"line_number":363,"context_line":"  service_type \u003d \u0027volume\u0027"},{"line_number":364,"context_line":"  # volume not in authority or catalog"},{"line_number":365,"context_line":"  # volume is an alias of block-storage"},{"line_number":366,"context_line":"  # block-storage is not found. Return error."},{"line_number":367,"context_line":""},{"line_number":368,"context_line":"  service_type \u003d \u0027volume\u0027"},{"line_number":369,"context_line":"  api_version \u003d 2"},{"line_number":370,"context_line":"  # volume not in authority or catalog"},{"line_number":371,"context_line":"  # volume is an alias of block-storage"},{"line_number":372,"context_line":"  # block-storage is not found."},{"line_number":373,"context_line":"  # volumev2 is an alias of block-storage and ends with v2 which matches"},{"line_number":374,"context_line":"  #   api_version of 2"},{"line_number":375,"context_line":"  # return volumev2"},{"line_number":376,"context_line":""},{"line_number":377,"context_line":"Given the following catalog:"},{"line_number":378,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_316b5fb7","line":375,"range":{"start_line":355,"start_character":0,"end_line":375,"end_character":19},"updated":"2019-03-28 16:33:17.000000000","message":"It would be clearer if these chunks could be split into separate boxes when rendered. Does adding an extra :: line in between do that?\n\nLikewise below","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":461,"context_line":"  # block-storage does not have internal, but has public"},{"line_number":462,"context_line":"  # return block-storage public"},{"line_number":463,"context_line":""},{"line_number":464,"context_line":"  service_type \u003d \u0027volumev2\u0027"},{"line_number":465,"context_line":"  interface \u003d [\u0027internal\u0027, \u0027public\u0027]"},{"line_number":466,"context_line":"  # volumev2 not an official type in authority, but is in catalog"},{"line_number":467,"context_line":"  # volumev2 has an internal interface"},{"line_number":468,"context_line":"  # return volumev2 internal entry"},{"line_number":469,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_f15157da","line":469,"range":{"start_line":464,"start_character":0,"end_line":469,"end_character":0},"updated":"2019-03-28 16:33:17.000000000","message":"This might be more interesting (or add as a separate example) as:\n\n service_type \u003d \u0027volumev2\u0027\n interface \u003d [\u0027admin\u0027, \u0027internal\u0027, \u0027public\u0027]\n # volumev2 not an official type in authority, but is in catalog\n # volumev2 has no admin interface\n # volumev2 has an internal interface\n # return volumev2 internal entry\n # (ignore volumev2 public entry since a match was found for internal)","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"}],"guidelines/consuming-catalog/version-discovery.rst":[{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":14,"context_line":""},{"line_number":15,"context_line":".. note:: This document contains references to dealing with all known forms"},{"line_number":16,"context_line":"          of things encountered in the wild. Where it doesn\u0027t distract from the"},{"line_number":17,"context_line":"          rest of the description, care is taken to indicate which form is the"},{"line_number":18,"context_line":"          preferred form and which are supported for legacy reasons."},{"line_number":19,"context_line":"          Mention of a form in this document should not be construed as"},{"line_number":20,"context_line":"          endorsement. Definitions of preferred forms of data will be found"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_b12f4f3d","line":17,"range":{"start_line":17,"start_character":67,"end_line":17,"end_character":71},"updated":"2019-03-28 16:33:17.000000000","message":"strike","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":60,"context_line":""},{"line_number":61,"context_line":"At this point, there is a matrix of four possibilities:"},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"#. If ``{endpoint-version}`` is ``latest`` and ``{single-or-multiple}`` is"},{"line_number":64,"context_line":"   ``single``, follow `Latest Single Version`_."},{"line_number":65,"context_line":""},{"line_number":66,"context_line":"#. If ``{endpoint-version}`` is ``latest`` and ``{single-or-multiple}`` is"},{"line_number":67,"context_line":"   ``multiple``, follow `Latest Multiple Versions`_."},{"line_number":68,"context_line":""},{"line_number":69,"context_line":"#. If ``{endpoint-version}`` is a version and ``{single-or-multiple}`` is"},{"line_number":70,"context_line":"   ``single``, follow `Requested Single Version`_."},{"line_number":71,"context_line":""},{"line_number":72,"context_line":"#. If ``{endpoint-version}`` is a version and ``{single-or-multiple}`` is"},{"line_number":73,"context_line":"   ``multiple``, follow `Requested Multiple Versions`_."},{"line_number":74,"context_line":""},{"line_number":75,"context_line":"User Omitted API Version"},{"line_number":76,"context_line":"------------------------"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_51914b51","line":73,"range":{"start_line":63,"start_character":0,"end_line":73,"end_character":55},"updated":"2019-03-28 16:33:17.000000000","message":"wonder if this would play better as a table of some kind...","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":148,"context_line":"   the new ``{discovery-endpoint}``."},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"#. If the current ``{discovery-endpoint}`` ends with a path element that ends"},{"line_number":151,"context_line":"   with a version string of the form \"v[0-9]+(\\.[0-9]+)?$\", remove that path"},{"line_number":152,"context_line":"   element but save it as ``{removed-version-path-element}``. Make the"},{"line_number":153,"context_line":"   resulting URL the new ``{discovery-endpoint}``."},{"line_number":154,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_71fd676c","line":151,"range":{"start_line":151,"start_character":37,"end_line":151,"end_character":58},"updated":"2019-03-28 16:33:17.000000000","message":"``literal`` this","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":157,"context_line":""},{"line_number":158,"context_line":"#. Attempt to fetch a ``{discovery-document}`` from the"},{"line_number":159,"context_line":"   ``{discovery-endpoint}``. If one exists, STOP. Normalize it (see"},{"line_number":160,"context_line":"   `Normalizing Documents`_) and return it as the ``{dicovery-document}``."},{"line_number":161,"context_line":""},{"line_number":162,"context_line":"#. If no new ``{discovery-document}`` can be found at the new endpoint but"},{"line_number":163,"context_line":"   there is a saved value in ``{removed-version-path-element}``, append"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_b12c2f02","line":160,"range":{"start_line":160,"start_character":53,"end_line":160,"end_character":61},"updated":"2019-03-28 16:33:17.000000000","message":"discovery","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":301,"context_line":"  # The catalog_endpoint ends with the user\u0027s project_id, so we pop it."},{"line_number":302,"context_line":"  discovery_endpoint \u003d \u0027https://file-storage.example.com/v2\u0027"},{"line_number":303,"context_line":""},{"line_number":304,"context_line":"  # We try to fetch https://file-storage.example.com/v2 but it returns an error"},{"line_number":305,"context_line":""},{"line_number":306,"context_line":"  # Pop version string from the endpoint"},{"line_number":307,"context_line":"  new_discovery_endpoint \u003d \u0027https://file-storage.example.com/\u0027"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_3157df5a","line":304,"range":{"start_line":304,"start_character":63,"end_line":304,"end_character":79},"updated":"2019-03-28 16:33:17.000000000","message":"Even though it\u0027s a valid endpoint as seen on L328? Presumably because the versioned endpoint doesn\u0027t expose a discovery document? And maybe the root URI there requires authentication, or doesn\u0027t have a handler, or whatever?\n\nIt might be nice to add some of that to the comment.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":344,"context_line":"the version of the service at the ``{service-endpoint}``. In some cases no"},{"line_number":345,"context_line":"discovery document can be found corresponding with the ``{service-endpoint}``"},{"line_number":346,"context_line":"in question. Alternately, in some cases the ``{catalog-endpoint}`` contains"},{"line_number":347,"context_line":"version information and the user is not looking for microversion information."},{"line_number":348,"context_line":""},{"line_number":349,"context_line":"Microversion information will always be empty when this procedure is used."},{"line_number":350,"context_line":""},{"line_number":351,"context_line":"The algorithm for inferring the version is as follows:"},{"line_number":352,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_b1966fef","line":349,"range":{"start_line":347,"start_character":20,"end_line":349,"end_character":74},"updated":"2019-03-28 16:33:17.000000000","message":"I don\u0027t get where microversions came into the picture","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":392,"context_line":"Matching Endpoints"},{"line_number":393,"context_line":"------------------"},{"line_number":394,"context_line":""},{"line_number":395,"context_line":"If ``{single-or-multiple}`` is ``multiple`` and the discovery algorithm has"},{"line_number":396,"context_line":"chosen to fall back to the endpoint provided by the catalog, a URL matching the"},{"line_number":397,"context_line":"catalog URL should be found so that the version can be extracted."},{"line_number":398,"context_line":""}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_d150db34","line":395,"range":{"start_line":395,"start_character":4,"end_line":395,"end_character":27},"updated":"2019-03-28 16:33:17.000000000","message":"Reading this document sequentially, the whole single-or-multiple thing hasn\u0027t been explained yet. Perhaps move this below the Single or Multiple Version Documents section; or move that section up above this one.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":411,"context_line":""},{"line_number":412,"context_line":"  discovery_document \u003d {"},{"line_number":413,"context_line":"    \"versions\": ["},{"line_number":414,"context_line":"      {"},{"line_number":415,"context_line":"        \"status\": \"CURRENT\","},{"line_number":416,"context_line":"        \"id\": \"v2.0\","},{"line_number":417,"context_line":"        \"links\": ["},{"line_number":418,"context_line":"          {"},{"line_number":419,"context_line":"            \"href\": \"http://file-storage.example.com/v2/\","},{"line_number":420,"context_line":"            \"rel\": \"self\""},{"line_number":421,"context_line":"          }"},{"line_number":422,"context_line":"        ],"},{"line_number":423,"context_line":"      }"},{"line_number":424,"context_line":"    ]"},{"line_number":425,"context_line":"  }"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_310fdf37","line":422,"range":{"start_line":414,"start_character":0,"end_line":422,"end_character":10},"updated":"2019-03-28 16:33:17.000000000","message":"This would be more interesting if it had multiple versions, so we\u0027re also applying the part of the algorithm on L399.","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":480,"context_line":".. code-block:: python"},{"line_number":481,"context_line":""},{"line_number":482,"context_line":"  project_id \u003d \u002745f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":483,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":484,"context_line":""},{"line_number":485,"context_line":"  discovery_document \u003d {"},{"line_number":486,"context_line":"    \"versions\": ["}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_ac77f29f","line":483,"range":{"start_line":483,"start_character":58,"end_line":483,"end_character":60},"updated":"2019-03-28 16:33:17.000000000","message":"to exemplify the note at L474, consider prefixing this...","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":503,"context_line":"  # Apply URL join to https://file-storage.example.com/v2 and /v2.0"},{"line_number":504,"context_line":"  joined_endpoint \u003d \u0027https://file-storage.example.com/v2.0\u0027"},{"line_number":505,"context_line":""},{"line_number":506,"context_line":"  # catalog_endpoint ends with project_id, append project_id"},{"line_number":507,"context_line":"  service_endpoint \u003d \u0027http://file-storage.example.com/v2.0/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":508,"context_line":""},{"line_number":509,"context_line":"With broken service endpoint in discovery:"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_cc9fdeb1","line":506,"range":{"start_line":506,"start_character":43,"end_line":506,"end_character":60},"updated":"2019-03-28 16:33:17.000000000","message":"...and clarify that this is the project_id-plus-prefix stripped from the catalog_endpoint (L483), *not* the value of project_id (L482).","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":693,"context_line":"  }"},{"line_number":694,"context_line":""},{"line_number":695,"context_line":"* If the document has a key named ``version``, (even if you just created it)"},{"line_number":696,"context_line":"  grab the ``href`` for the link where ``rel`` is ``self`` link. If the"},{"line_number":697,"context_line":"  ``href`` ends with with a version string of the form \"v[0-9]+(\\.[0-9]*)?$\","},{"line_number":698,"context_line":"  pop that element from the end of the endpoint and add an entry to the"},{"line_number":699,"context_line":"  ``links`` list with a ``rel`` of ``collection`` and the resulting endpoint."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_ccd6fe4f","line":696,"range":{"start_line":696,"start_character":58,"end_line":696,"end_character":63},"updated":"2019-03-28 16:33:17.000000000","message":"strike","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":729,"context_line":"          \"rel\": \"self\""},{"line_number":730,"context_line":"        },"},{"line_number":731,"context_line":"        {"},{"line_number":732,"context_line":"          \"href\": \"http://network.example.com/\","},{"line_number":733,"context_line":"          \"rel\": \"collection\""},{"line_number":734,"context_line":"        }"},{"line_number":735,"context_line":"      ]"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_ac38529f","line":732,"range":{"start_line":732,"start_character":19,"end_line":732,"end_character":46},"updated":"2019-03-28 16:33:17.000000000","message":"hm, up to now we might have zero indication that there\u0027s anything at this endpoint, nah?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":847,"context_line":"        \"links\": ["},{"line_number":848,"context_line":"          {"},{"line_number":849,"context_line":"            \"href\": \"https://auth.example.com/v3/\","},{"line_number":850,"context_line":"            \"rel\": \"self\""},{"line_number":851,"context_line":"          }"},{"line_number":852,"context_line":"        ]"},{"line_number":853,"context_line":"      },"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_2cfa22bc","line":850,"updated":"2019-03-28 16:33:17.000000000","message":"these don\u0027t get\n\n \"href\": \"https://auth.example.com/\"\n \"rel\": \"collection\"\n\n?","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":1044,"context_line":"#. STOP. Return the information in ``{endpoint-information}`` (see"},{"line_number":1045,"context_line":"   `Return Information`_)."},{"line_number":1046,"context_line":""},{"line_number":1047,"context_line":"Find Latest Version"},{"line_number":1048,"context_line":"-------------------"},{"line_number":1049,"context_line":""},{"line_number":1050,"context_line":"If one of the versions in the list has ``status`` of ``CURRENT``, use it."}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_8cab1686","line":1047,"range":{"start_line":1047,"start_character":0,"end_line":1047,"end_character":19},"updated":"2019-03-28 16:33:17.000000000","message":"This section should go first under the preamble for Find Matching Version","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":1050,"context_line":"If one of the versions in the list has ``status`` of ``CURRENT``, use it."},{"line_number":1051,"context_line":""},{"line_number":1052,"context_line":"Otherwise, select the version with the highest ``id``, excluding any with"},{"line_number":1053,"context_line":"``status`` of ``EXPERIMENTAL`` or ``DEPRECATED`` sorted using version"},{"line_number":1054,"context_line":"comparison not lexical sorting."},{"line_number":1055,"context_line":""},{"line_number":1056,"context_line":"Return Information"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_ec9bba6f","line":1053,"range":{"start_line":1053,"start_character":47,"end_line":1053,"end_character":49},"updated":"2019-03-28 16:33:17.000000000","message":"comma here","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"a3731b9a3729277afa0d31c686621f0722802c6c","unresolved":false,"context_lines":[{"line_number":1051,"context_line":""},{"line_number":1052,"context_line":"Otherwise, select the version with the highest ``id``, excluding any with"},{"line_number":1053,"context_line":"``status`` of ``EXPERIMENTAL`` or ``DEPRECATED`` sorted using version"},{"line_number":1054,"context_line":"comparison not lexical sorting."},{"line_number":1055,"context_line":""},{"line_number":1056,"context_line":"Return Information"},{"line_number":1057,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":29,"id":"5fc1f717_cc8efe2c","line":1054,"range":{"start_line":1054,"start_character":10,"end_line":1054,"end_character":11},"updated":"2019-03-28 16:33:17.000000000","message":"and here","commit_id":"608d193456471b3e4fbd658f3eba5d566f7ed6e5"}],"guidelines/consuming-discovery.rst":[{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":18,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":19,"context_line":""},{"line_number":20,"context_line":"The ultimate goal of this process is for a user to find the information about"},{"line_number":21,"context_line":"the endpoint for a service given some inputs. The user will start the process"},{"line_number":22,"context_line":"with some number of these parameters:"},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"service-type"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_8d12c408","line":21,"range":{"start_line":21,"start_character":0,"end_line":21,"end_character":3},"updated":"2017-04-25 16:55:42.000000000","message":"NIT: an endpoint","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":25,"context_line":"  The common name of the service, such as ``compute``, ``image`` or"},{"line_number":26,"context_line":"  ``file-storage`` as listed in the `OpenStack Service Types Authority`_."},{"line_number":27,"context_line":"  It is impossible for a user to consume service discovery without knowing"},{"line_number":28,"context_line":"  what service they want to discover."},{"line_number":29,"context_line":"api-version"},{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_52c1f4e3","line":28,"updated":"2017-04-25 21:54:57.000000000","message":"Not sure how this renders, but having a blank line between each of these parameters would sure make it easier to read in Gerrit.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":25,"context_line":"  The common name of the service, such as ``compute``, ``image`` or"},{"line_number":26,"context_line":"  ``file-storage`` as listed in the `OpenStack Service Types Authority`_."},{"line_number":27,"context_line":"  It is impossible for a user to consume service discovery without knowing"},{"line_number":28,"context_line":"  what service they want to discover."},{"line_number":29,"context_line":"api-version"},{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_efe492ae","line":28,"in_reply_to":"5ff73747_52c1f4e3","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":28,"context_line":"  what service they want to discover."},{"line_number":29,"context_line":"api-version"},{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4d9efc54","line":31,"range":{"start_line":31,"start_character":10,"end_line":31,"end_character":15},"updated":"2017-04-25 16:55:42.000000000","message":"NIT: Please provide extra guidance on the preferred form. Suggest saying \"can provide v\", preferred without \"v\". or similar.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":28,"context_line":"  what service they want to discover."},{"line_number":29,"context_line":"api-version"},{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_92f89c49","line":31,"range":{"start_line":31,"start_character":10,"end_line":31,"end_character":15},"in_reply_to":"5ff73747_4d9efc54","updated":"2017-04-25 21:54:57.000000000","message":"That should really be in a separate document, since this is about \u0027consuming\u0027. We don\u0027t yet have a guideline for constructing URIs, though; perhaps we could put it in the API discovery doc? So maybe a blurb near the top explaining that this document contains references to all the forms encountered in the wild, and that the preferred forms can be found at \u003csome new document that I\u0027m sure Monty would love to write\u003e.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":28,"context_line":"  what service they want to discover."},{"line_number":29,"context_line":"api-version"},{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_cff8b64a","line":31,"range":{"start_line":31,"start_character":10,"end_line":31,"end_character":15},"in_reply_to":"5ff73747_92f89c49","updated":"2017-04-25 22:37:50.000000000","message":"I agree with both of you.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"},{"line_number":35,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":36,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_edb828c9","line":33,"range":{"start_line":33,"start_character":33,"end_line":33,"end_character":43},"updated":"2017-04-25 16:55:42.000000000","message":"Does \"vLATEST\" work?","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"},{"line_number":35,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":36,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_5298d419","line":33,"range":{"start_line":33,"start_character":33,"end_line":33,"end_character":43},"in_reply_to":"5ff73747_edb828c9","updated":"2017-04-25 21:54:57.000000000","message":"God I hope not :)","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":30,"context_line":"  The version of the service the user desires to work with. Can include a"},{"line_number":31,"context_line":"  leading ``v`` or not. Can be specific (``v3.1.23``) or vague (``v3``)."},{"line_number":32,"context_line":"  A user can also desire to work with the latest available version, in which"},{"line_number":33,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":34,"context_line":"  versions, which will be given as a comma-separated tuple, such as"},{"line_number":35,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":36,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4c039474","line":33,"range":{"start_line":33,"start_character":33,"end_line":33,"end_character":43},"in_reply_to":"5ff73747_edb828c9","updated":"2017-04-25 22:37:50.000000000","message":"zomg it should. ;)","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  A user can also omit the api-version indicating that they want to use"},{"line_number":40,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":41,"context_line":"region-name"},{"line_number":42,"context_line":"  The region of the service the user desires to work with. If the cloud has"},{"line_number":43,"context_line":"  only one region, this may be omitted. If the cloud has more than one region"},{"line_number":44,"context_line":"  it is required."},{"line_number":45,"context_line":"interface"},{"line_number":46,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":47,"context_line":"  the user wants to use. In some older OpenStack usage this concept was known"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4df5dc82","line":44,"range":{"start_line":42,"start_character":1,"end_line":44,"end_character":17},"updated":"2017-04-25 16:55:42.000000000","message":"Suggest ensure we always require a region... the \"omitted\" may be for legacy compat, but api-wg specs are guidance going forward. Best is to set guidance for the preferred form.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  A user can also omit the api-version indicating that they want to use"},{"line_number":40,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":41,"context_line":"region-name"},{"line_number":42,"context_line":"  The region of the service the user desires to work with. If the cloud has"},{"line_number":43,"context_line":"  only one region, this may be omitted. If the cloud has more than one region"},{"line_number":44,"context_line":"  it is required."},{"line_number":45,"context_line":"interface"},{"line_number":46,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":47,"context_line":"  the user wants to use. In some older OpenStack usage this concept was known"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_ecf3809d","line":44,"range":{"start_line":42,"start_character":1,"end_line":44,"end_character":17},"in_reply_to":"5ff73747_4df5dc82","updated":"2017-04-25 22:37:50.000000000","message":"I lean towards agreeing, but there are a lot of single-region clouds out there. Lemme poke at words.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  A user can also omit the api-version indicating that they want to use"},{"line_number":40,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":41,"context_line":"region-name"},{"line_number":42,"context_line":"  The region of the service the user desires to work with. If the cloud has"},{"line_number":43,"context_line":"  only one region, this may be omitted. If the cloud has more than one region"},{"line_number":44,"context_line":"  it is required."},{"line_number":45,"context_line":"interface"},{"line_number":46,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":47,"context_line":"  the user wants to use. In some older OpenStack usage this concept was known"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_523454fb","line":44,"range":{"start_line":42,"start_character":1,"end_line":44,"end_character":17},"in_reply_to":"5ff73747_4df5dc82","updated":"2017-04-25 21:54:57.000000000","message":"There are a bunch (all of the following, actually) where these parameters are optional. Since multiple regions is not a requirement, nor even common, I think it is best to keep this parameter optional, too.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":39,"context_line":"  A user can also omit the api-version indicating that they want to use"},{"line_number":40,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":41,"context_line":"region-name"},{"line_number":42,"context_line":"  The region of the service the user desires to work with. If the cloud has"},{"line_number":43,"context_line":"  only one region, this may be omitted. If the cloud has more than one region"},{"line_number":44,"context_line":"  it is required."},{"line_number":45,"context_line":"interface"},{"line_number":46,"context_line":"  Which API interface, such as ``public``, ``internal`` or ``admin`` that"},{"line_number":47,"context_line":"  the user wants to use. In some older OpenStack usage this concept was known"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_6fb88275","line":44,"range":{"start_line":42,"start_character":1,"end_line":44,"end_character":17},"in_reply_to":"5ff73747_523454fb","updated":"2017-04-25 22:37:50.000000000","message":"Yah - that\u0027s where I came down too - I\u0027ve got better text in the next draft now.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":76,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":77,"context_line":"min-version"},{"line_number":78,"context_line":"  If the service supports microversions, what is the minimum microversion the"},{"line_number":79,"context_line":"  service supports. (Optional, defaults to omitted)"},{"line_number":80,"context_line":""},{"line_number":81,"context_line":"If the process was unsuccessful:"},{"line_number":82,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_d81c0315","line":79,"updated":"2017-04-25 21:54:57.000000000","message":"And if https://review.openstack.org/#/c/446138/ is approved, we will also have \u0027next_min_version\u0027","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":90,"context_line":"supplied input to the process or one of the expected outputs is being"},{"line_number":91,"context_line":"discussed. Other values that are fetched at one point in the process and"},{"line_number":92,"context_line":"referred to at a later point are similarly referred to like"},{"line_number":93,"context_line":"``{service-catalog}``. It can be assumed that names will not be reused to"},{"line_number":94,"context_line":"hold different content."},{"line_number":95,"context_line":""},{"line_number":96,"context_line":"It is also assumed that the user has an ``{auth-url}`` and authentication"},{"line_number":97,"context_line":"information. The authentication process itself is out of the scope of this"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_edc70812","line":94,"range":{"start_line":93,"start_character":23,"end_line":94,"end_character":23},"updated":"2017-04-25 16:55:42.000000000","message":"Suggest being more authoritative here, \"names must/will be unique and cannot be reused to hold different content\".","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":93,"context_line":"``{service-catalog}``. It can be assumed that names will not be reused to"},{"line_number":94,"context_line":"hold different content."},{"line_number":95,"context_line":""},{"line_number":96,"context_line":"It is also assumed that the user has an ``{auth-url}`` and authentication"},{"line_number":97,"context_line":"information. The authentication process itself is out of the scope of this"},{"line_number":98,"context_line":"document."},{"line_number":99,"context_line":""},{"line_number":100,"context_line":".. _OpenStack Service Types Authority: http://git.openstack.org/cgit/openstack/service-types-authority/"},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_add100d0","line":98,"range":{"start_line":96,"start_character":0,"end_line":98,"end_character":9},"updated":"2017-04-25 16:55:42.000000000","message":"Nice definition of the document scope.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":110,"context_line":"#. Authenticate to keystone at the ``{auth-url}``, retreiving a ``token``"},{"line_number":111,"context_line":"   which contains the ``{service-catalog}``."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"#. Retreive ``{catalog-endpoint}`` from the ``{service-catalog}`` given"},{"line_number":114,"context_line":"   ``{service-type}``, ``{interface}`` and ``{region-name}``. (see"},{"line_number":115,"context_line":"   :ref:`endpoint-from-catalog`)"},{"line_number":116,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_0c658ce1","line":113,"range":{"start_line":113,"start_character":3,"end_line":113,"end_character":11},"updated":"2017-04-25 21:54:57.000000000","message":"i before e...","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":110,"context_line":"#. Authenticate to keystone at the ``{auth-url}``, retreiving a ``token``"},{"line_number":111,"context_line":"   which contains the ``{service-catalog}``."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"#. Retreive ``{catalog-endpoint}`` from the ``{service-catalog}`` given"},{"line_number":114,"context_line":"   ``{service-type}``, ``{interface}`` and ``{region-name}``. (see"},{"line_number":115,"context_line":"   :ref:`endpoint-from-catalog`)"},{"line_number":116,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_6f3be2ea","line":113,"range":{"start_line":113,"start_character":3,"end_line":113,"end_character":11},"in_reply_to":"5ff73747_0c658ce1","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":349,"context_line":"or will not return the document we want, so we need to look for a new one. The"},{"line_number":350,"context_line":"algorithm for that is as follows:"},{"line_number":351,"context_line":""},{"line_number":352,"context_line":"#. If the current ``{discovery-endpoint}`` ends with a version string of the"},{"line_number":353,"context_line":"   form \"v[0-9]+.*\", pop that element from the end of the endpoint and attempt"},{"line_number":354,"context_line":"   to fetch a ``{discovery-document}`` from the resulting URL. If one exists,"},{"line_number":355,"context_line":"   return it as the new ``{dicovery-document}`` and make the new endpoint"},{"line_number":356,"context_line":"   the current ``{discovery-endpoint}``"},{"line_number":357,"context_line":""},{"line_number":358,"context_line":"#. Get the curently scoped ``project_id`` from the ``token``, if one exists."},{"line_number":359,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_68740669","line":356,"range":{"start_line":352,"start_character":0,"end_line":356,"end_character":39},"updated":"2017-04-25 16:55:42.000000000","message":"While you and I both know why this is done, please add a note as to why we preferr the root discovery doc vs the vXXX one for clarity.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":349,"context_line":"or will not return the document we want, so we need to look for a new one. The"},{"line_number":350,"context_line":"algorithm for that is as follows:"},{"line_number":351,"context_line":""},{"line_number":352,"context_line":"#. If the current ``{discovery-endpoint}`` ends with a version string of the"},{"line_number":353,"context_line":"   form \"v[0-9]+.*\", pop that element from the end of the endpoint and attempt"},{"line_number":354,"context_line":"   to fetch a ``{discovery-document}`` from the resulting URL. If one exists,"},{"line_number":355,"context_line":"   return it as the new ``{dicovery-document}`` and make the new endpoint"},{"line_number":356,"context_line":"   the current ``{discovery-endpoint}``"},{"line_number":357,"context_line":""},{"line_number":358,"context_line":"#. Get the curently scoped ``project_id`` from the ``token``, if one exists."},{"line_number":359,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_2c04c849","line":356,"range":{"start_line":352,"start_character":0,"end_line":356,"end_character":39},"in_reply_to":"5ff73747_68740669","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":349,"context_line":"or will not return the document we want, so we need to look for a new one. The"},{"line_number":350,"context_line":"algorithm for that is as follows:"},{"line_number":351,"context_line":""},{"line_number":352,"context_line":"#. If the current ``{discovery-endpoint}`` ends with a version string of the"},{"line_number":353,"context_line":"   form \"v[0-9]+.*\", pop that element from the end of the endpoint and attempt"},{"line_number":354,"context_line":"   to fetch a ``{discovery-document}`` from the resulting URL. If one exists,"},{"line_number":355,"context_line":"   return it as the new ``{dicovery-document}`` and make the new endpoint"},{"line_number":356,"context_line":"   the current ``{discovery-endpoint}``"},{"line_number":357,"context_line":""},{"line_number":358,"context_line":"#. Get the curently scoped ``project_id`` from the ``token``, if one exists."},{"line_number":359,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_2c228853","line":356,"range":{"start_line":352,"start_character":0,"end_line":356,"end_character":39},"in_reply_to":"5ff73747_68740669","updated":"2017-04-25 21:54:57.000000000","message":"Yeah, I\u0027d like to know why!","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":377,"context_line":"For example::"},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"  project_id \u003d \u0027db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":380,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage-ca-ymq-1.vexxhost.net/v2/db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":381,"context_line":""},{"line_number":382,"context_line":"  # GET catalog_endpoint returns 404"},{"line_number":383,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_88b992ea","line":380,"range":{"start_line":380,"start_character":20,"end_line":380,"end_character":64},"updated":"2017-04-25 16:55:42.000000000","message":"Suggest not using a real example cloud. Use something fabricated (replace vexxhost.net with something clearly example-ish). This is just to be clear it isn\u0027t vexxhost specific or add to confusion.\n\nThis applies to all the examples.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":377,"context_line":"For example::"},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"  project_id \u003d \u0027db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":380,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage-ca-ymq-1.vexxhost.net/v2/db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":381,"context_line":""},{"line_number":382,"context_line":"  # GET catalog_endpoint returns 404"},{"line_number":383,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4f3ee6da","line":380,"range":{"start_line":380,"start_character":20,"end_line":380,"end_character":64},"in_reply_to":"5ff73747_0ce22c02","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":377,"context_line":"For example::"},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"  project_id \u003d \u0027db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":380,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage-ca-ymq-1.vexxhost.net/v2/db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":381,"context_line":""},{"line_number":382,"context_line":"  # GET catalog_endpoint returns 404"},{"line_number":383,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4cbb9471","line":380,"range":{"start_line":380,"start_character":20,"end_line":380,"end_character":64},"in_reply_to":"5ff73747_88b992ea","updated":"2017-04-25 22:37:50.000000000","message":"But making REST calls to vexxhost and pasting my results was easier. :) Done.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"102c17e7c2916228e378e7b8a3a2851b3c0ae22e","unresolved":false,"context_lines":[{"line_number":377,"context_line":"For example::"},{"line_number":378,"context_line":""},{"line_number":379,"context_line":"  project_id \u003d \u0027db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":380,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage-ca-ymq-1.vexxhost.net/v2/db92b20496ae4fbda850a689ea9d563f\u0027"},{"line_number":381,"context_line":""},{"line_number":382,"context_line":"  # GET catalog_endpoint returns 404"},{"line_number":383,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_0ce22c02","line":380,"range":{"start_line":380,"start_character":20,"end_line":380,"end_character":64},"in_reply_to":"5ff73747_88b992ea","updated":"2017-04-25 21:54:57.000000000","message":"example.com is what you need","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":577,"context_line":"            parsed_endpoint.query,"},{"line_number":578,"context_line":"            parsed_endpoint.fragment).geturl()"},{"line_number":579,"context_line":""},{"line_number":580,"context_line":"#. If a ``{endpoint_project_id}`` is set append it to the end of the endpoint."},{"line_number":581,"context_line":""},{"line_number":582,"context_line":"For example::"},{"line_number":583,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_082a228f","line":580,"range":{"start_line":580,"start_character":3,"end_line":580,"end_character":78},"updated":"2017-04-25 16:55:42.000000000","message":"Check to make sure we haven\u0027t defined this in places that don\u0027t have the explicit substitution added in the Keystone catalog returned based on the written out algorithm here.\n\nKeystone explicitly substitutes the project_id into the catalog when scoped based on the endpoint definition.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":577,"context_line":"            parsed_endpoint.query,"},{"line_number":578,"context_line":"            parsed_endpoint.fragment).geturl()"},{"line_number":579,"context_line":""},{"line_number":580,"context_line":"#. If a ``{endpoint_project_id}`` is set append it to the end of the endpoint."},{"line_number":581,"context_line":""},{"line_number":582,"context_line":"For example::"},{"line_number":583,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_4fea66ac","line":580,"range":{"start_line":580,"start_character":3,"end_line":580,"end_character":78},"in_reply_to":"5ff73747_082a228f","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":644,"context_line":"Single or Multiple Version Documents"},{"line_number":645,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":646,"context_line":""},{"line_number":647,"context_line":"There are three forms of version discovery documents in the wild, two that"},{"line_number":648,"context_line":"contain lists of endpoint versions and one that is for a single version. In"},{"line_number":649,"context_line":"order to apply the discovery algorithm, the type of document must be detected."},{"line_number":650,"context_line":""},{"line_number":651,"context_line":"* If the document has a top level key of ``versions`` with a subkey of"},{"line_number":652,"context_line":"  ``values``, it is a multiple version document."},{"line_number":653,"context_line":""},{"line_number":654,"context_line":".. code-block:: json"},{"line_number":655,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_e3283987","line":652,"range":{"start_line":647,"start_character":0,"end_line":652,"end_character":48},"updated":"2017-04-25 16:55:42.000000000","message":"Suggest defining the preferred/modern version of this, indicate the other ones should be supported but again give guidance on the most correct form(s).","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":644,"context_line":"Single or Multiple Version Documents"},{"line_number":645,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":646,"context_line":""},{"line_number":647,"context_line":"There are three forms of version discovery documents in the wild, two that"},{"line_number":648,"context_line":"contain lists of endpoint versions and one that is for a single version. In"},{"line_number":649,"context_line":"order to apply the discovery algorithm, the type of document must be detected."},{"line_number":650,"context_line":""},{"line_number":651,"context_line":"* If the document has a top level key of ``versions`` with a subkey of"},{"line_number":652,"context_line":"  ``values``, it is a multiple version document."},{"line_number":653,"context_line":""},{"line_number":654,"context_line":".. code-block:: json"},{"line_number":655,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_0fcc5e5f","line":652,"range":{"start_line":647,"start_character":0,"end_line":652,"end_character":48},"in_reply_to":"5ff73747_e3283987","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":734,"context_line":"    ]"},{"line_number":735,"context_line":"  }"},{"line_number":736,"context_line":""},{"line_number":737,"context_line":"* If the document has a top level key of ``version``, it is a single version"},{"line_number":738,"context_line":"  document."},{"line_number":739,"context_line":""},{"line_number":740,"context_line":".. code-block:: json"},{"line_number":741,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_a357d102","line":738,"range":{"start_line":737,"start_character":0,"end_line":738,"end_character":11},"updated":"2017-04-25 16:55:42.000000000","message":"i would personally like to see this form die and move everything to one of the multiple \"versions\" even if there is a single element.\n\nThis should be legacy-support only (based on API-WG forward looking guidance)","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":734,"context_line":"    ]"},{"line_number":735,"context_line":"  }"},{"line_number":736,"context_line":""},{"line_number":737,"context_line":"* If the document has a top level key of ``version``, it is a single version"},{"line_number":738,"context_line":"  document."},{"line_number":739,"context_line":""},{"line_number":740,"context_line":".. code-block:: json"},{"line_number":741,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_cfee76b3","line":738,"range":{"start_line":737,"start_character":0,"end_line":738,"end_character":11},"in_reply_to":"5ff73747_a357d102","updated":"2017-04-25 22:37:50.000000000","message":"Yah - I agree, although I think we\u0027re less likely to get that changed than we are to get a single global cache of all multi-version discovery - so i figure saving that battle for later ...","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":767,"context_line":"  }"},{"line_number":768,"context_line":""},{"line_number":769,"context_line":""},{"line_number":770,"context_line":"* If the document has neither but is a single dict that contains a key of"},{"line_number":771,"context_line":"  ``id``, it is a single version document."},{"line_number":772,"context_line":""},{"line_number":773,"context_line":".. code-block:: json"},{"line_number":774,"context_line":""},{"line_number":775,"context_line":"  {"},{"line_number":776,"context_line":"    \"status\": \"CURRENT\","},{"line_number":777,"context_line":"    \"id\": \"v2.0\","},{"line_number":778,"context_line":"    \"links\": ["},{"line_number":779,"context_line":"      {"},{"line_number":780,"context_line":"        \"href\": \"http://network-ca-ymq-1.vexxhost.net/v2.0\","},{"line_number":781,"context_line":"        \"rel\": \"self\""},{"line_number":782,"context_line":"      }"},{"line_number":783,"context_line":"    ]"},{"line_number":784,"context_line":"  }"},{"line_number":785,"context_line":""},{"line_number":786,"context_line":".. _normalize-document:"},{"line_number":787,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_636ae9b3","line":784,"range":{"start_line":770,"start_character":0,"end_line":784,"end_character":3},"updated":"2017-04-25 16:55:42.000000000","message":"see above comment about forms that should die but legacy-support.","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"3d10e93dbec7c91951b14eca410cd1229a354530","unresolved":false,"context_lines":[{"line_number":919,"context_line":""},{"line_number":920,"context_line":"Finding a version out of a list of endpoint descriptions is done by comparing"},{"line_number":921,"context_line":"the given version with the ``id`` field of the description. Leading ``v``"},{"line_number":922,"context_line":"characters should be discarded/ignored."},{"line_number":923,"context_line":""},{"line_number":924,"context_line":"A given version should match any version that matches as many segements of"},{"line_number":925,"context_line":"precision that are given. Thus, an ``{api-version}`` of ``v2`` should match an"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_c39e5db7","line":922,"range":{"start_line":922,"start_character":11,"end_line":922,"end_character":17},"updated":"2017-04-25 16:55:42.000000000","message":"s/should be/are","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"9ca4f297a7e335a5e4c1145f377a147629c51afc","unresolved":false,"context_lines":[{"line_number":919,"context_line":""},{"line_number":920,"context_line":"Finding a version out of a list of endpoint descriptions is done by comparing"},{"line_number":921,"context_line":"the given version with the ``id`` field of the description. Leading ``v``"},{"line_number":922,"context_line":"characters should be discarded/ignored."},{"line_number":923,"context_line":""},{"line_number":924,"context_line":"A given version should match any version that matches as many segements of"},{"line_number":925,"context_line":"precision that are given. Thus, an ``{api-version}`` of ``v2`` should match an"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5ff73747_af2b2ae9","line":922,"range":{"start_line":922,"start_character":11,"end_line":922,"end_character":17},"in_reply_to":"5ff73747_c39e5db7","updated":"2017-04-25 22:37:50.000000000","message":"Done","commit_id":"06e117d3fb21656c446bbe4b152fbe01da5f9d06"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e61a04162149abe1fa4a2635f1ababac80811c95","unresolved":false,"context_lines":[{"line_number":6,"context_line":""},{"line_number":7,"context_line":"The topic document on :ref:`discoverability` describes how REST services can"},{"line_number":8,"context_line":"expose version discovery information. However, due to seven years of existence"},{"line_number":9,"context_line":"that pre-dates the existing of that document, there are a few non-optimal"},{"line_number":10,"context_line":"setups in the wild. This document describes the complete algorithm to correctly"},{"line_number":11,"context_line":"consume OpenStack version discovery. The intent with this algorithm is that for"},{"line_number":12,"context_line":"all clouds that fully implement :ref:`discoverability` guidelines the path"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_91e523ab","line":9,"updated":"2017-04-26 13:05:40.000000000","message":"do you want existence here too?","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f14cd62655905870db11dfdbe1d7354cdcf2b64c","unresolved":false,"context_lines":[{"line_number":6,"context_line":""},{"line_number":7,"context_line":"The topic document on :ref:`discoverability` describes how REST services can"},{"line_number":8,"context_line":"expose version discovery information. However, due to seven years of existence"},{"line_number":9,"context_line":"that pre-dates the existing of that document, there are a few non-optimal"},{"line_number":10,"context_line":"setups in the wild. This document describes the complete algorithm to correctly"},{"line_number":11,"context_line":"consume OpenStack version discovery. The intent with this algorithm is that for"},{"line_number":12,"context_line":"all clouds that fully implement :ref:`discoverability` guidelines the path"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_f67c54ec","line":9,"in_reply_to":"5ff73747_91e523ab","updated":"2017-04-26 16:58:04.000000000","message":"Done","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e61a04162149abe1fa4a2635f1ababac80811c95","unresolved":false,"context_lines":[{"line_number":16,"context_line":""},{"line_number":17,"context_line":".. note:: This document contains references to dealing with all known forms"},{"line_number":18,"context_line":"          of things encountered in the wild. Where it doesn\u0027t distract from the"},{"line_number":19,"context_line":"          rest of the description care is taken to indicate which form is the"},{"line_number":20,"context_line":"          preferred form and which are supported for legacy reasons."},{"line_number":21,"context_line":"          Mention of a form in this document should not be constituted as"},{"line_number":22,"context_line":"          endorsement. Definitions of preferred forms of data will be found"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_b1725fe2","line":19,"updated":"2017-04-26 13:05:40.000000000","message":", care","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f14cd62655905870db11dfdbe1d7354cdcf2b64c","unresolved":false,"context_lines":[{"line_number":16,"context_line":""},{"line_number":17,"context_line":".. note:: This document contains references to dealing with all known forms"},{"line_number":18,"context_line":"          of things encountered in the wild. Where it doesn\u0027t distract from the"},{"line_number":19,"context_line":"          rest of the description care is taken to indicate which form is the"},{"line_number":20,"context_line":"          preferred form and which are supported for legacy reasons."},{"line_number":21,"context_line":"          Mention of a form in this document should not be constituted as"},{"line_number":22,"context_line":"          endorsement. Definitions of preferred forms of data will be found"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_16634044","line":19,"in_reply_to":"5ff73747_b1725fe2","updated":"2017-04-26 16:58:04.000000000","message":"Done","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e61a04162149abe1fa4a2635f1ababac80811c95","unresolved":false,"context_lines":[{"line_number":419,"context_line":""},{"line_number":420,"context_line":"For example::"},{"line_number":421,"context_line":""},{"line_number":422,"context_line":"  project_id \u003d \u002745f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":423,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":424,"context_line":""},{"line_number":425,"context_line":"  # GET catalog_endpoint returns 404"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_2c88326f","line":422,"updated":"2017-04-26 13:05:40.000000000","message":"argggggghhhhhhhh!","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f14cd62655905870db11dfdbe1d7354cdcf2b64c","unresolved":false,"context_lines":[{"line_number":419,"context_line":""},{"line_number":420,"context_line":"For example::"},{"line_number":421,"context_line":""},{"line_number":422,"context_line":"  project_id \u003d \u002745f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":423,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":424,"context_line":""},{"line_number":425,"context_line":"  # GET catalog_endpoint returns 404"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_b65fec70","line":422,"in_reply_to":"5ff73747_2c88326f","updated":"2017-04-26 16:58:04.000000000","message":"IKR?","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e61a04162149abe1fa4a2635f1ababac80811c95","unresolved":false,"context_lines":[{"line_number":842,"context_line":".. code-block:: json"},{"line_number":843,"context_line":""},{"line_number":844,"context_line":"  {"},{"line_number":845,"context_line":"    \"version\": {"},{"line_number":846,"context_line":"      \"status\": \"CURRENT\","},{"line_number":847,"context_line":"      \"id\": \"v2.0\","},{"line_number":848,"context_line":"      \"links\": ["}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_cc4b0e29","line":845,"updated":"2017-04-26 13:05:40.000000000","message":"should this be a list of length one contain the single-version object?","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"f14cd62655905870db11dfdbe1d7354cdcf2b64c","unresolved":false,"context_lines":[{"line_number":842,"context_line":".. code-block:: json"},{"line_number":843,"context_line":""},{"line_number":844,"context_line":"  {"},{"line_number":845,"context_line":"    \"version\": {"},{"line_number":846,"context_line":"      \"status\": \"CURRENT\","},{"line_number":847,"context_line":"      \"id\": \"v2.0\","},{"line_number":848,"context_line":"      \"links\": ["}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_d6d158cf","line":845,"in_reply_to":"5ff73747_cc4b0e29","updated":"2017-04-26 16:58:04.000000000","message":"Not currently - BUT - after chatting with Morgan I\u0027ve got an idea to make that actually be the case. So, yes.","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e61a04162149abe1fa4a2635f1ababac80811c95","unresolved":false,"context_lines":[{"line_number":1024,"context_line":""},{"line_number":1025,"context_line":"Finding a version out of a list of endpoint descriptions is done by comparing"},{"line_number":1026,"context_line":"the given version with the ``id`` field of the description. Leading ``v``"},{"line_number":1027,"context_line":"characters are be discarded/ignored."},{"line_number":1028,"context_line":""},{"line_number":1029,"context_line":"A given version should match any version that matches as many segements of"},{"line_number":1030,"context_line":"precision that are given. Thus, an ``{api-version}`` of ``2`` should match an"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5ff73747_acf442d0","line":1027,"updated":"2017-04-26 13:05:40.000000000","message":"\"are\" to \"should\" or \"must\"?","commit_id":"26755b9f6fd5b1898e845af83bd5322928de5a57"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"8e117ce95628d104fd1ec5a5dddcec52d28735fb","unresolved":false,"context_lines":[{"line_number":18,"context_line":"          of things encountered in the wild. Where it doesn\u0027t distract from the"},{"line_number":19,"context_line":"          rest of the description, care is taken to indicate which form is the"},{"line_number":20,"context_line":"          preferred form and which are supported for legacy reasons."},{"line_number":21,"context_line":"          Mention of a form in this document should not be constituted as"},{"line_number":22,"context_line":"          endorsement. Definitions of preferred forms of data will be found"},{"line_number":23,"context_line":"          in other documents."},{"line_number":24,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5ff73747_edea350d","line":21,"range":{"start_line":21,"start_character":59,"end_line":21,"end_character":70},"updated":"2017-04-26 20:46:20.000000000","message":"s/constituted/construed","commit_id":"76d540737a7d1241640783e00eff29d5f6d678b6"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"d3ebfc3379806adea8ea300403e1b2bee29c4f4d","unresolved":false,"context_lines":[{"line_number":18,"context_line":"          of things encountered in the wild. Where it doesn\u0027t distract from the"},{"line_number":19,"context_line":"          rest of the description, care is taken to indicate which form is the"},{"line_number":20,"context_line":"          preferred form and which are supported for legacy reasons."},{"line_number":21,"context_line":"          Mention of a form in this document should not be constituted as"},{"line_number":22,"context_line":"          endorsement. Definitions of preferred forms of data will be found"},{"line_number":23,"context_line":"          in other documents."},{"line_number":24,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5ff73747_d5724ead","line":21,"range":{"start_line":21,"start_character":59,"end_line":21,"end_character":70},"in_reply_to":"5ff73747_edea350d","updated":"2017-04-27 12:25:12.000000000","message":"Done","commit_id":"76d540737a7d1241640783e00eff29d5f6d678b6"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"8e117ce95628d104fd1ec5a5dddcec52d28735fb","unresolved":false,"context_lines":[{"line_number":48,"context_line":"or additional constraints the user might wish to express."},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"region-name"},{"line_number":51,"context_line":"  The region of the service the user desires to work with. Optional. Services"},{"line_number":52,"context_line":"  all exist within regions, but some clouds only have one region. On clouds"},{"line_number":53,"context_line":"  that have more than one region, ``{region-name}`` is required input from"},{"line_number":54,"context_line":"  the user. (It is highly recommended that ``{region-name}`` always be"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5ff73747_ad578dca","line":51,"range":{"start_line":51,"start_character":59,"end_line":51,"end_character":67},"updated":"2017-04-26 20:46:20.000000000","message":"\"May be optional, depending on whether the cloud has more than one region.\"","commit_id":"76d540737a7d1241640783e00eff29d5f6d678b6"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"d3ebfc3379806adea8ea300403e1b2bee29c4f4d","unresolved":false,"context_lines":[{"line_number":48,"context_line":"or additional constraints the user might wish to express."},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"region-name"},{"line_number":51,"context_line":"  The region of the service the user desires to work with. Optional. Services"},{"line_number":52,"context_line":"  all exist within regions, but some clouds only have one region. On clouds"},{"line_number":53,"context_line":"  that have more than one region, ``{region-name}`` is required input from"},{"line_number":54,"context_line":"  the user. (It is highly recommended that ``{region-name}`` always be"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5ff73747_b56b42b5","line":51,"range":{"start_line":51,"start_character":59,"end_line":51,"end_character":67},"in_reply_to":"5ff73747_ad578dca","updated":"2017-04-27 12:25:12.000000000","message":"Done","commit_id":"76d540737a7d1241640783e00eff29d5f6d678b6"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"70f89a3a2a4319e6d198e25a44e08a8e59c564b1","unresolved":false,"context_lines":[{"line_number":6,"context_line":""},{"line_number":7,"context_line":"The topic document on :ref:`discoverability` describes how REST services can"},{"line_number":8,"context_line":"expose version discovery information. However, due to seven years of existence"},{"line_number":9,"context_line":"that pre-dates the existence of that document, there are a few non-optimal"},{"line_number":10,"context_line":"setups in the wild. This document describes the complete algorithm to correctly"},{"line_number":11,"context_line":"consume OpenStack version discovery. The intent with this algorithm is that for"},{"line_number":12,"context_line":"all clouds that fully implement :ref:`discoverability` guidelines the path"}],"source_content_type":"text/x-rst","patch_set":7,"id":"5ff73747_563ccc2d","line":9,"range":{"start_line":9,"start_character":5,"end_line":9,"end_character":14},"updated":"2017-04-28 21:40:59.000000000","message":"Since it is \u0027years\u0027 being modified, this should be \u0027pre-date\u0027. I.e., \"due to seven years that pre-date the document\".\n\nThanks for beating that stuff into me, grade-school nuns.","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"83d70fd8d728d9eabfa43cacc5520e4a1c0b9d75","unresolved":false,"context_lines":[{"line_number":6,"context_line":""},{"line_number":7,"context_line":"The topic document on :ref:`discoverability` describes how REST services can"},{"line_number":8,"context_line":"expose version discovery information. However, due to seven years of existence"},{"line_number":9,"context_line":"that pre-dates the existence of that document, there are a few non-optimal"},{"line_number":10,"context_line":"setups in the wild. This document describes the complete algorithm to correctly"},{"line_number":11,"context_line":"consume OpenStack version discovery. The intent with this algorithm is that for"},{"line_number":12,"context_line":"all clouds that fully implement :ref:`discoverability` guidelines the path"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3f044301_ab5920ff","line":9,"range":{"start_line":9,"start_character":5,"end_line":9,"end_character":14},"in_reply_to":"5ff73747_563ccc2d","updated":"2017-05-04 13:20:58.000000000","message":"Done","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"70f89a3a2a4319e6d198e25a44e08a8e59c564b1","unresolved":false,"context_lines":[{"line_number":65,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":66,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":67,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":68,"context_line":"  versions, which will be given as a comma-separated tuple, such as"},{"line_number":69,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":70,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"},{"line_number":71,"context_line":"  things like shade or terraform may have internal logic that can handle more"}],"source_content_type":"text/x-rst","patch_set":7,"id":"5ff73747_762a28db","line":68,"range":{"start_line":68,"start_character":53,"end_line":68,"end_character":58},"updated":"2017-04-28 21:40:59.000000000","message":"As a pythonista, this makes perfect sense to me, but for the uninitiated, \u0027list\u0027 might be better word here.","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"83d70fd8d728d9eabfa43cacc5520e4a1c0b9d75","unresolved":false,"context_lines":[{"line_number":65,"context_line":"  whatever endpoint is in the ``{service-catalog}``."},{"line_number":66,"context_line":"  A user can desire to work with the latest available version, in which"},{"line_number":67,"context_line":"  case the api-version should be ``LATEST``. Can also be a range of acceptable"},{"line_number":68,"context_line":"  versions, which will be given as a comma-separated tuple, such as"},{"line_number":69,"context_line":"  ``2.0,3.0``. It may seem strange from an individual user perspective to"},{"line_number":70,"context_line":"  want a range or ``LATEST`` - but from a library and framework perspective,"},{"line_number":71,"context_line":"  things like shade or terraform may have internal logic that can handle more"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3f044301_cb646cbc","line":68,"range":{"start_line":68,"start_character":53,"end_line":68,"end_character":58},"in_reply_to":"5ff73747_762a28db","updated":"2017-05-04 13:20:58.000000000","message":"Done","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"70f89a3a2a4319e6d198e25a44e08a8e59c564b1","unresolved":false,"context_lines":[{"line_number":81,"context_line":"  the most extreme cases this should never be needed and its use as a"},{"line_number":82,"context_line":"  meaningful identified is strongly discouraged. For completeness though, there"},{"line_number":83,"context_line":"  is at least one case in the wild where service-name has been required in"},{"line_number":84,"context_line":"  addition to service-type to uniquely identify the right service."},{"line_number":85,"context_line":""},{"line_number":86,"context_line":"endpoint-override"},{"line_number":87,"context_line":"  An endpoint for the service that the user has procurred from some other"}],"source_content_type":"text/x-rst","patch_set":7,"id":"5ff73747_f67bd8f1","line":84,"updated":"2017-04-28 21:40:59.000000000","message":"I know which one that is!","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"83d70fd8d728d9eabfa43cacc5520e4a1c0b9d75","unresolved":false,"context_lines":[{"line_number":81,"context_line":"  the most extreme cases this should never be needed and its use as a"},{"line_number":82,"context_line":"  meaningful identified is strongly discouraged. For completeness though, there"},{"line_number":83,"context_line":"  is at least one case in the wild where service-name has been required in"},{"line_number":84,"context_line":"  addition to service-type to uniquely identify the right service."},{"line_number":85,"context_line":""},{"line_number":86,"context_line":"endpoint-override"},{"line_number":87,"context_line":"  An endpoint for the service that the user has procurred from some other"}],"source_content_type":"text/x-rst","patch_set":7,"id":"5ff73747_86dfb567","line":84,"in_reply_to":"5ff73747_f67bd8f1","updated":"2017-05-04 13:20:58.000000000","message":"sssh. it\u0027s a sekrit!","commit_id":"6e3bf2cf38af0b38640d95775b7117cab23f65d0"}],"guidelines/consuming-version-discovery.rst":[{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"bcaa4df637cd26cb7ef9bc2fa9c11535f9785521","unresolved":false,"context_lines":[{"line_number":58,"context_line":""},{"line_number":59,"context_line":"At this point, there is a matrix of four possibilities:"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"If ``{api-version}`` is ``LATEST`` and ``{document-type}`` is ``single``,"},{"line_number":62,"context_line":"follow :ref:`latest-single-version`."},{"line_number":63,"context_line":""},{"line_number":64,"context_line":"If ``{api-version}`` is ``LATEST`` and ``{document-type}`` is ``multiple``,"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_c0342b4d","line":61,"updated":"2017-05-18 12:04:56.000000000","message":"we changed the case on this elsewhere. or is this yet another something different?\n\nIt\u0027s a bit confusing because while we\u0027re using LATEST as a user input, there are also all caps things in the discovery document, but _not_ LATEST","commit_id":"2d31298b3f12fa5e99847cbd9645893e8bc5b2ec"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"12b8579d5e4fec0a2ad6eb66e157ae2d0c1aae58","unresolved":false,"context_lines":[{"line_number":58,"context_line":""},{"line_number":59,"context_line":"At this point, there is a matrix of four possibilities:"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"If ``{api-version}`` is ``LATEST`` and ``{document-type}`` is ``single``,"},{"line_number":62,"context_line":"follow :ref:`latest-single-version`."},{"line_number":63,"context_line":""},{"line_number":64,"context_line":"If ``{api-version}`` is ``LATEST`` and ``{document-type}`` is ``multiple``,"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ff0f0b1f_13739f17","line":61,"in_reply_to":"ff0f0b1f_c0342b4d","updated":"2017-05-18 12:36:55.000000000","message":"Nope - it\u0027s the same and it should be lowercase.","commit_id":"2d31298b3f12fa5e99847cbd9645893e8bc5b2ec"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"f945e91bcdfe16f4ef364915504e3473bf9f41f0","unresolved":false,"context_lines":[{"line_number":181,"context_line":"If the user has supplied ``{endpoint-override}`` they already know the"},{"line_number":182,"context_line":"``{service-endpoint}`` and the purpose of discovery is a best-effort attempt"},{"line_number":183,"context_line":"to find out version information about the service at ``{service-endpoint}``."},{"line_number":184,"context_line":"Errors should not be returned from attempts to find version information, as"},{"line_number":185,"context_line":"there are historical services that do not return version discovery information"},{"line_number":186,"context_line":"at all and the user has indicated they know what they\u0027re doing by providing an"},{"line_number":187,"context_line":"override."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"#. ``{service-endpoint}`` is ``{endpoint-override}``."},{"line_number":190,"context_line":""}],"source_content_type":"text/x-rst","patch_set":19,"id":"ff0f0b1f_ae7b8fbc","line":187,"range":{"start_line":184,"start_character":0,"end_line":187,"end_character":8},"updated":"2019-04-22 17:43:29.000000000","message":"There should be an option to still return errors. This is good default behavior.","commit_id":"7c69bc48d96be22dd79c505a26a2bcbd92b20c92"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":31,"context_line":""},{"line_number":32,"context_line":"The algorithm is as follows:"},{"line_number":33,"context_line":""},{"line_number":34,"context_line":"#. If the ``{service-type}`` is either ``object-store`` or ``ec2-api``, STOP."},{"line_number":35,"context_line":"   There is no version discovery. Use ``{catalog-endpoint}`` as"},{"line_number":36,"context_line":"   ``{service-endpoint}``.  Infer the ``{service-version}``."},{"line_number":37,"context_line":"   (see :ref:`inferring-version`)"},{"line_number":38,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_187ef318","line":35,"range":{"start_line":34,"start_character":2,"end_line":35,"end_character":33},"updated":"2017-05-31 19:26:41.000000000","message":"Could the rationale for this be documented?\n\nAlso, wouldn\u0027t this fall into Inferring Version -\u003e Endpoint contains no version elements, or Finding a Document -\u003e No new endpoint can be found, and therefor not need to be special cased?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":31,"context_line":""},{"line_number":32,"context_line":"The algorithm is as follows:"},{"line_number":33,"context_line":""},{"line_number":34,"context_line":"#. If the ``{service-type}`` is either ``object-store`` or ``ec2-api``, STOP."},{"line_number":35,"context_line":"   There is no version discovery. Use ``{catalog-endpoint}`` as"},{"line_number":36,"context_line":"   ``{service-endpoint}``.  Infer the ``{service-version}``."},{"line_number":37,"context_line":"   (see :ref:`inferring-version`)"},{"line_number":38,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_e5ba2b6c","line":35,"range":{"start_line":34,"start_character":2,"end_line":35,"end_character":33},"in_reply_to":"df140735_187ef318","updated":"2017-10-05 16:28:48.000000000","message":"Yes, you are right. And actually, from having written the keystoneauth patches, there is an optimization that can be added. (if the user is not requesting microversion information and the endpoint in the catalog is versioned and either matches the version requested or there was no version requested, there is no need to fetch a discovery document)","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":85,"context_line":"   and expand it (see :ref:`expanding-endpoints`) Return the information in"},{"line_number":86,"context_line":"   the document. (see :ref:`return-information`)"},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"#. Attempt to find a better ``{discovery-document}``. (see"},{"line_number":89,"context_line":"   :ref:`find-document`)"},{"line_number":90,"context_line":""},{"line_number":91,"context_line":"#. If there is a new ``{discovery-document}``, normalize it (see"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_e3c0307f","line":88,"range":{"start_line":88,"start_character":21,"end_line":88,"end_character":27},"updated":"2017-05-31 19:26:41.000000000","message":"better \u003d\u003d has status CURRENT?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":85,"context_line":"   and expand it (see :ref:`expanding-endpoints`) Return the information in"},{"line_number":86,"context_line":"   the document. (see :ref:`return-information`)"},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"#. Attempt to find a better ``{discovery-document}``. (see"},{"line_number":89,"context_line":"   :ref:`find-document`)"},{"line_number":90,"context_line":""},{"line_number":91,"context_line":"#. If there is a new ``{discovery-document}``, normalize it (see"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_c57de6b2","line":88,"range":{"start_line":88,"start_character":21,"end_line":88,"end_character":27},"in_reply_to":"df140735_e3c0307f","updated":"2017-10-05 16:28:48.000000000","message":"Better \u003d\u003d result of Find a Document process. Will rewrite.","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":88,"context_line":"#. Attempt to find a better ``{discovery-document}``. (see"},{"line_number":89,"context_line":"   :ref:`find-document`)"},{"line_number":90,"context_line":""},{"line_number":91,"context_line":"#. If there is a new ``{discovery-document}``, normalize it (see"},{"line_number":92,"context_line":"   :ref:`normalize-document`) and determine if the ``{document-type}``"},{"line_number":93,"context_line":"   is ``single`` or ``multiple`` (see :ref:`single-or-multiple`)"},{"line_number":94,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_839bb4c7","line":91,"range":{"start_line":91,"start_character":17,"end_line":91,"end_character":20},"updated":"2017-05-31 19:26:41.000000000","message":"new \u003d\u003d has status CURRENT?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":88,"context_line":"#. Attempt to find a better ``{discovery-document}``. (see"},{"line_number":89,"context_line":"   :ref:`find-document`)"},{"line_number":90,"context_line":""},{"line_number":91,"context_line":"#. If there is a new ``{discovery-document}``, normalize it (see"},{"line_number":92,"context_line":"   :ref:`normalize-document`) and determine if the ``{document-type}``"},{"line_number":93,"context_line":"   is ``single`` or ``multiple`` (see :ref:`single-or-multiple`)"},{"line_number":94,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_854dae9b","line":91,"range":{"start_line":91,"start_character":17,"end_line":91,"end_character":20},"in_reply_to":"df140735_839bb4c7","updated":"2017-10-05 16:28:48.000000000","message":"New  means \u0027Find a Document\u0027 returned a new document. Will rewrite.","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":141,"context_line":""},{"line_number":142,"context_line":"#. If ``{be-strict}`` is ``False``, use ``{catalog-endpoint}``"},{"line_number":143,"context_line":"   as the ``{service-endpoint}`` and return the version information in the"},{"line_number":144,"context_line":"   ``{discovery-document}``. (see :ref:`return-information`)"},{"line_number":145,"context_line":""},{"line_number":146,"context_line":".. _requested-multiple-version:"},{"line_number":147,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_a3eb58da","line":144,"updated":"2017-05-31 19:26:41.000000000","message":"What does be-strict default to? I would expect this to always be strict and to always fail if I request an invalid version instead of trying to be smart for me.","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":141,"context_line":""},{"line_number":142,"context_line":"#. If ``{be-strict}`` is ``False``, use ``{catalog-endpoint}``"},{"line_number":143,"context_line":"   as the ``{service-endpoint}`` and return the version information in the"},{"line_number":144,"context_line":"   ``{discovery-document}``. (see :ref:`return-information`)"},{"line_number":145,"context_line":""},{"line_number":146,"context_line":".. _requested-multiple-version:"},{"line_number":147,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_a5f79259","line":144,"in_reply_to":"df140735_a3eb58da","updated":"2017-10-05 16:28:48.000000000","message":"be-strict defaults to False for backwards compat. However, I think this makes a great point - which is that the input parameters from the catalog discovery document aren\u0027t referenced in this document.","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":266,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"In some cases, the ``{discovery-endpoint}`` will either not return a document,"},{"line_number":269,"context_line":"or will not return the document we want, so we need to look for a new one."},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"The Unversioned Document is always preferred over the Versioned Document,"},{"line_number":272,"context_line":"becaues the Unversioned Document supplies the list of possible versions,"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_2fedef8a","line":269,"range":{"start_line":269,"start_character":3,"end_line":269,"end_character":39},"updated":"2017-05-31 19:26:41.000000000","message":"More detail? How do we know what we want, and how do we say that?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":269,"context_line":"or will not return the document we want, so we need to look for a new one."},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"The Unversioned Document is always preferred over the Versioned Document,"},{"line_number":272,"context_line":"becaues the Unversioned Document supplies the list of possible versions,"},{"line_number":273,"context_line":"allowing Discovery to process the list and make decisions in on step. The"},{"line_number":274,"context_line":"Versioned Document only contains one Version, so additional calls must be"},{"line_number":275,"context_line":"made if the version in it does not match the user\u0027s request."}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_aff8df48","line":272,"range":{"start_line":272,"start_character":0,"end_line":272,"end_character":7},"updated":"2017-05-31 19:26:41.000000000","message":"typo","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":468,"context_line":""},{"line_number":469,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":470,"context_line":"  # Match path elements - /v2/ matches ..."},{"line_number":471,"context_line":"  service_version \u003d \u0027v2\u0027"},{"line_number":472,"context_line":""},{"line_number":473,"context_line":"  catalog_endpoint \u003d \u0027https://identity-storage.example.com/\u0027"},{"line_number":474,"context_line":"  # Match path elements - no matches"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_f81c5f14","line":471,"range":{"start_line":471,"start_character":20,"end_line":471,"end_character":24},"updated":"2017-05-31 19:26:41.000000000","message":"This is inconsistent with step 2 in this algorithm - \"strip the v and use the rest as ``{service-version}``\"","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":487,"context_line":"to fall back to the endpoint provided by the catalog, a URL matching the"},{"line_number":488,"context_line":"catalog URL should be found so that the version can be extracted."},{"line_number":489,"context_line":""},{"line_number":490,"context_line":"#. Sort the endpoints in the ``{discovery-document}`` by ``id`` in descending"},{"line_number":491,"context_line":"   using version comparision."},{"line_number":492,"context_line":""},{"line_number":493,"context_line":"#. For each endpoint in the list, expand it (see :ref:`expanding-endpoints`)"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_23eaa8ab","line":490,"range":{"start_line":490,"start_character":67,"end_line":490,"end_character":77},"updated":"2017-05-31 19:26:41.000000000","message":"descending order","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":560,"context_line":""},{"line_number":561,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":562,"context_line":""},{"line_number":563,"context_line":"#. If the ``{catalog_endpoint}`` ends with ``project_id`` but the endpoint"},{"line_number":564,"context_line":"   does not, append the ``project_id`` to the end of the endpoint."},{"line_number":565,"context_line":""},{"line_number":566,"context_line":"For example:"}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_23a2a84c","line":563,"range":{"start_line":563,"start_character":13,"end_line":563,"end_character":29},"updated":"2017-05-31 19:26:41.000000000","message":"catalog-endpoint","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":922,"context_line":"   nova, cinder, manila and ironic microversions)"},{"line_number":923,"context_line":""},{"line_number":924,"context_line":"#. The ``links`` key should contain a list, and that list should contain one"},{"line_number":925,"context_line":"   dict with ``rel`` equal to ``self`` and additional may contain a second"},{"line_number":926,"context_line":"   dict with ``rel`` equal to ``collection``. Any other entries can be"},{"line_number":927,"context_line":"   discarded."},{"line_number":928,"context_line":""}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_7e8f1723","line":925,"range":{"start_line":925,"start_character":43,"end_line":925,"end_character":53},"updated":"2017-05-31 19:26:41.000000000","message":"additionally","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":1079,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1080,"context_line":""},{"line_number":1081,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1082,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1083,"context_line":""},{"line_number":1084,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1085,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_c2a63d54","line":1082,"updated":"2017-05-31 19:26:41.000000000","message":"Maybe this would never happen in real life, but is it worth considering what would happen if an API defined more than one version as CURRENT?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":1079,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1080,"context_line":""},{"line_number":1081,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1082,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1083,"context_line":""},{"line_number":1084,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1085,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_5f807fbf","line":1082,"in_reply_to":"df140735_c2a63d54","updated":"2017-10-05 16:28:48.000000000","message":"I haven\u0027t ever seen that, and I think we should somewhere define that services should definitely NOT do that. However, for completeness, I think grabbing the CURRENT version with the highest matching version would be the right choice, no?","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":8482,"name":"Colleen Murphy","email":"colleen@gazlene.net","username":"krinkle"},"change_message_id":"389e9681541a42a804ac47c0fc1a3f8cfee30a89","unresolved":false,"context_lines":[{"line_number":1108,"context_line":"#. If ``required`` is a range, any ``candidate`` that is greater than or equal"},{"line_number":1109,"context_line":"   to the first value and less than or equal to the second value is a match."},{"line_number":1110,"context_line":"   Equality is judged by the above rules. Greater than and less than are judged"},{"line_number":1111,"context_line":"   expected: first by comparing the first digit, and if those match then by"},{"line_number":1112,"context_line":"   comparing the second digit.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":1113,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":1114,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."}],"source_content_type":"text/x-rst","patch_set":22,"id":"df140735_e2fdc13a","line":1111,"range":{"start_line":1111,"start_character":3,"end_line":1111,"end_character":11},"updated":"2017-05-31 19:26:41.000000000","message":"as expected","commit_id":"2a5f67c074a8dfbbb22c906c987bb7f25fdf15d0"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"2ead9f4e99b96646b700df119a592e07caa2df1f","unresolved":false,"context_lines":[{"line_number":818,"context_line":""},{"line_number":819,"context_line":"* If the document has a key named ``version``, (even if you just created it)"},{"line_number":820,"context_line":"  grab the ``href`` for the link where ``rel`` is ``self`` link. If the"},{"line_number":821,"context_line":"  ``href`` with a version string of the form \"v[0-9]+(\\.[0-9]*)?$\", pop that"},{"line_number":822,"context_line":"  element from the end of the endpoint and add an entry to the ``links`` list"},{"line_number":823,"context_line":"  with a ``rel`` of ``collection`` and the resulting endpoint."},{"line_number":824,"context_line":""}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_fe609ea7","line":821,"updated":"2017-06-01 17:01:47.000000000","message":"``href`` ends with...","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"2ead9f4e99b96646b700df119a592e07caa2df1f","unresolved":false,"context_lines":[{"line_number":922,"context_line":"   nova, cinder, manila and ironic microversions)"},{"line_number":923,"context_line":""},{"line_number":924,"context_line":"#. The ``links`` key should contain a list, and that list should contain one"},{"line_number":925,"context_line":"   dict with ``rel`` equal to ``self`` and additional may contain a second"},{"line_number":926,"context_line":"   dict with ``rel`` equal to ``collection``. Any other entries can be"},{"line_number":927,"context_line":"   discarded."},{"line_number":928,"context_line":""}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_fed3fe36","line":925,"updated":"2017-06-01 17:01:47.000000000","message":"s/additional/additionally/","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"2f036a151c6fce900c2960d7fae58775851b1e88","unresolved":false,"context_lines":[{"line_number":922,"context_line":"   nova, cinder, manila and ironic microversions)"},{"line_number":923,"context_line":""},{"line_number":924,"context_line":"#. The ``links`` key should contain a list, and that list should contain one"},{"line_number":925,"context_line":"   dict with ``rel`` equal to ``self`` and additional may contain a second"},{"line_number":926,"context_line":"   dict with ``rel`` equal to ``collection``. Any other entries can be"},{"line_number":927,"context_line":"   discarded."},{"line_number":928,"context_line":""}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_646173a9","line":925,"in_reply_to":"df140735_fed3fe36","updated":"2017-06-02 19:13:15.000000000","message":"Done","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"2ead9f4e99b96646b700df119a592e07caa2df1f","unresolved":false,"context_lines":[{"line_number":1079,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1080,"context_line":""},{"line_number":1081,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1082,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1083,"context_line":""},{"line_number":1084,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1085,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_9e03e273","line":1082,"updated":"2017-06-01 17:01:47.000000000","message":"[Followup to Colleen\u0027s question in PS22: Maybe this would never happen in real life, but is it worth considering what would happen if an API defined more than one version as CURRENT?]\n\nI would expect that we do the same thing as when no CURRENT (below) is present, return the highest one?","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"2f036a151c6fce900c2960d7fae58775851b1e88","unresolved":false,"context_lines":[{"line_number":1079,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1080,"context_line":""},{"line_number":1081,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1082,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1083,"context_line":""},{"line_number":1084,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1085,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_c4715f78","line":1082,"in_reply_to":"df140735_9e03e273","updated":"2017-06-02 19:13:15.000000000","message":"Yah. I think that\u0027s the right choice.","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a4e0db46b69b73add208bd75d75e1ec5c13ccecd","unresolved":false,"context_lines":[{"line_number":1108,"context_line":"#. If ``required`` is a range, any ``candidate`` that is greater than or equal"},{"line_number":1109,"context_line":"   to the first value and less than or equal to the second value is a match."},{"line_number":1110,"context_line":"   Equality is judged by the above rules. Greater than and less than are judged"},{"line_number":1111,"context_line":"   expected: first by comparing the first digit, and if those match then by"},{"line_number":1112,"context_line":"   comparing the second digit.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":1113,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":1114,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_4050ced4","line":1111,"range":{"start_line":1111,"start_character":42,"end_line":1111,"end_character":47},"updated":"2017-06-01 13:49:19.000000000","message":"nit: a digit is a single character. A version string like \u002712.36\u0027 has 4 digits, but only two numbers. So \u0027number\u0027 might be a better term to use.","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"2f036a151c6fce900c2960d7fae58775851b1e88","unresolved":false,"context_lines":[{"line_number":1108,"context_line":"#. If ``required`` is a range, any ``candidate`` that is greater than or equal"},{"line_number":1109,"context_line":"   to the first value and less than or equal to the second value is a match."},{"line_number":1110,"context_line":"   Equality is judged by the above rules. Greater than and less than are judged"},{"line_number":1111,"context_line":"   expected: first by comparing the first digit, and if those match then by"},{"line_number":1112,"context_line":"   comparing the second digit.  Thus, a ``{required}`` of ``2,4`` matches"},{"line_number":1113,"context_line":"   ``2``, ``2.3``, ``3``, ``4`` and ``4.7``. A ``{required}`` of ``2.1,4.0``"},{"line_number":1114,"context_line":"   matches ``2.3``, ``3``, ``4`` and ``4.7`` but not ``2``."}],"source_content_type":"text/x-rst","patch_set":23,"id":"df140735_84fc87b5","line":1111,"range":{"start_line":1111,"start_character":42,"end_line":1111,"end_character":47},"in_reply_to":"df140735_4050ced4","updated":"2017-06-02 19:13:15.000000000","message":"Done","commit_id":"796dbd6820535fe4b237db36c21fed59a0add45c"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":27,"context_line":"Version Discovery Algorithm"},{"line_number":28,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"The Version Discovery Algorithm is a part of :ref:`consuming-catalog`. It\u0027s"},{"line_number":31,"context_line":"input parameters and return values are a subset of the input parameters and"},{"line_number":32,"context_line":"return values described in :ref:`catalog-user-request`."},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_c078c4f9","line":30,"range":{"start_line":30,"start_character":71,"end_line":30,"end_character":75},"updated":"2017-06-29 18:33:56.000000000","message":"Its","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":34,"context_line":"The algorithm is as follows:"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"#. If the user has omitted ``{api-version}``, follow"},{"line_number":37,"context_line":"   `User Omitted API Version`."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"#. If the user has supplied ``{endpoint-override}``, follow"},{"line_number":40,"context_line":"   `User Supplied Endpoint`."}],"source_content_type":"text/x-rst","patch_set":26,"id":"5f201791_180c093a","line":37,"range":{"start_line":37,"start_character":2,"end_line":37,"end_character":29},"updated":"2017-06-29 18:33:56.000000000","message":"Make these refs (throughout)","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":34,"context_line":"The algorithm is as follows:"},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"#. If the user has omitted ``{api-version}``, follow"},{"line_number":37,"context_line":"   `User Omitted API Version`."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"#. If the user has supplied ``{endpoint-override}``, follow"},{"line_number":40,"context_line":"   `User Supplied Endpoint`."}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_06aedf2d","line":37,"range":{"start_line":37,"start_character":2,"end_line":37,"end_character":29},"in_reply_to":"5f201791_180c093a","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":52,"context_line":""},{"line_number":53,"context_line":"#. If it is not possible to find a ``{discovery-document}`` and ``{be-strict}``"},{"line_number":54,"context_line":"   is true, STOP. Return an error that version discovery has failed."},{"line_number":55,"context_line":"   ``{catalog-endpoint}`` as ``{service-endpoint}``. Infer the"},{"line_number":56,"context_line":"   ``{found-api-version}``. (see `Inferring Version`)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"#. Determine if the ``{document-type}`` of the ``{discovery-document}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_60bc5069","line":55,"range":{"start_line":55,"start_character":3,"end_line":55,"end_character":51},"updated":"2017-06-29 18:33:56.000000000","message":"Is this missing words at the beginning of the sentence, or should it not be here at all?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":52,"context_line":""},{"line_number":53,"context_line":"#. If it is not possible to find a ``{discovery-document}`` and ``{be-strict}``"},{"line_number":54,"context_line":"   is true, STOP. Return an error that version discovery has failed."},{"line_number":55,"context_line":"   ``{catalog-endpoint}`` as ``{service-endpoint}``. Infer the"},{"line_number":56,"context_line":"   ``{found-api-version}``. (see `Inferring Version`)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"#. Determine if the ``{document-type}`` of the ``{discovery-document}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_e67f63a9","line":55,"range":{"start_line":55,"start_character":3,"end_line":55,"end_character":51},"in_reply_to":"3f1d235d_60bc5069","updated":"2017-07-12 15:30:44.000000000","message":"Let\u0027s go with not be here.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":55,"context_line":"   ``{catalog-endpoint}`` as ``{service-endpoint}``. Infer the"},{"line_number":56,"context_line":"   ``{found-api-version}``. (see `Inferring Version`)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"#. Determine if the ``{document-type}`` of the ``{discovery-document}``"},{"line_number":59,"context_line":"   is ``single`` or ``multiple`` (see :ref:`single-or-multiple`)"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":".. note:: If the :ref:`discoverability` guidelines have been implemented,"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_1babcdd6","line":58,"range":{"start_line":58,"start_character":22,"end_line":58,"end_character":37},"updated":"2017-06-29 18:33:56.000000000","message":"\u0027type\u0027 is so overloaded.  Can we maybe call it ``{document-multiplicity}``?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":55,"context_line":"   ``{catalog-endpoint}`` as ``{service-endpoint}``. Infer the"},{"line_number":56,"context_line":"   ``{found-api-version}``. (see `Inferring Version`)"},{"line_number":57,"context_line":""},{"line_number":58,"context_line":"#. Determine if the ``{document-type}`` of the ``{discovery-document}``"},{"line_number":59,"context_line":"   is ``single`` or ``multiple`` (see :ref:`single-or-multiple`)"},{"line_number":60,"context_line":""},{"line_number":61,"context_line":".. note:: If the :ref:`discoverability` guidelines have been implemented,"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_2112e559","line":58,"range":{"start_line":58,"start_character":22,"end_line":58,"end_character":37},"in_reply_to":"3f1d235d_1babcdd6","updated":"2017-07-12 15:30:44.000000000","message":"Done - went with \"single-or-multiple\"","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":72,"context_line":"If ``{api-version}`` is a version and ``{document-type}`` is ``single``,"},{"line_number":73,"context_line":"follow :ref:`requested-single-version`."},{"line_number":74,"context_line":""},{"line_number":75,"context_line":"#. ``{api-version}`` is a version and ``{document-type}`` is ``multiple``,"},{"line_number":76,"context_line":"follow :ref:`requested-multiple-version`."},{"line_number":77,"context_line":""},{"line_number":78,"context_line":".. _latest-single-version:"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_9b88fd71","line":75,"range":{"start_line":75,"start_character":0,"end_line":75,"end_character":2},"updated":"2017-06-29 18:33:56.000000000","message":"If","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":72,"context_line":"If ``{api-version}`` is a version and ``{document-type}`` is ``single``,"},{"line_number":73,"context_line":"follow :ref:`requested-single-version`."},{"line_number":74,"context_line":""},{"line_number":75,"context_line":"#. ``{api-version}`` is a version and ``{document-type}`` is ``multiple``,"},{"line_number":76,"context_line":"follow :ref:`requested-multiple-version`."},{"line_number":77,"context_line":""},{"line_number":78,"context_line":".. _latest-single-version:"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_010fe92e","line":75,"range":{"start_line":75,"start_character":0,"end_line":75,"end_character":2},"in_reply_to":"3f1d235d_9b88fd71","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":168,"context_line":""},{"line_number":169,"context_line":"#. If there is no ``{endpoint-information}``, STOP. Infer the"},{"line_number":170,"context_line":"   ``{found-api-version}`` from the ``{service-endpoint}``."},{"line_number":171,"context_line":"   (see `Inferring Version`)"},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"#. STOP. Return the information in ``{endpoint-information}``. (see"},{"line_number":174,"context_line":"   :ref:`return-information`)."}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_fb76d13e","line":171,"range":{"start_line":171,"start_character":8,"end_line":171,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":168,"context_line":""},{"line_number":169,"context_line":"#. If there is no ``{endpoint-information}``, STOP. Infer the"},{"line_number":170,"context_line":"   ``{found-api-version}`` from the ``{service-endpoint}``."},{"line_number":171,"context_line":"   (see `Inferring Version`)"},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"#. STOP. Return the information in ``{endpoint-information}``. (see"},{"line_number":174,"context_line":"   :ref:`return-information`)."}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_e11bcd70","line":171,"range":{"start_line":171,"start_character":8,"end_line":171,"end_character":27},"in_reply_to":"3f1d235d_fb76d13e","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":188,"context_line":""},{"line_number":189,"context_line":"#. If ``{skip-version-discovery}`` is True, STOP. Infer the"},{"line_number":190,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":191,"context_line":"   (see `Inferring Version`)"},{"line_number":192,"context_line":""},{"line_number":193,"context_line":"#. Retrieve ``{discovery-document}`` at ``{service-endpoint}``."},{"line_number":194,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_db73154d","line":191,"range":{"start_line":191,"start_character":8,"end_line":191,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":194,"context_line":""},{"line_number":195,"context_line":"#. If there is no ``{discovery-document}``, STOP. Infer the"},{"line_number":196,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":197,"context_line":"   (see `Inferring Version`)"},{"line_number":198,"context_line":""},{"line_number":199,"context_line":"#. If there is a ``{discovery-document}``, normalize it (see"},{"line_number":200,"context_line":"   :ref:`normalize-document`) and determine if the ``{document-type}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_bb8e1925","line":197,"range":{"start_line":197,"start_character":8,"end_line":197,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":209,"context_line":""},{"line_number":210,"context_line":"#. If there is no ``{endpoint-information}``, STOP. Infer the"},{"line_number":211,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":212,"context_line":"   (see `Inferring Version`)"},{"line_number":213,"context_line":""},{"line_number":214,"context_line":"#. STOP. Return the information in ``{endpoint-information}``. (see"},{"line_number":215,"context_line":"   :ref:`return-information`)."}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_7b988169","line":212,"range":{"start_line":212,"start_character":8,"end_line":212,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":223,"context_line":""},{"line_number":224,"context_line":"#. ``{service-endpoint}`` is ``{catalog-endpoint}``."},{"line_number":225,"context_line":""},{"line_number":226,"context_line":"#. If ``{fetch-version-information}`` is false, STOP. Infer the"},{"line_number":227,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":228,"context_line":"   (see `Inferring Version`)"},{"line_number":229,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_fb2011fa","line":226,"range":{"start_line":226,"start_character":9,"end_line":226,"end_character":34},"updated":"2017-06-29 18:33:56.000000000","message":"fetch-version-info (to match L45 and consuming-catalog)","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":225,"context_line":""},{"line_number":226,"context_line":"#. If ``{fetch-version-information}`` is false, STOP. Infer the"},{"line_number":227,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":228,"context_line":"   (see `Inferring Version`)"},{"line_number":229,"context_line":""},{"line_number":230,"context_line":"#. Retrieve ``{discovery-document}`` at ``{service-endpoint}``."},{"line_number":231,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_ad402009","line":228,"range":{"start_line":228,"start_character":8,"end_line":228,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":236,"context_line":""},{"line_number":237,"context_line":"#. If there is no ``{discovery-document}``, STOP Infer the"},{"line_number":238,"context_line":"   ``{found-api-version}`` from ``{service-endpoint}``."},{"line_number":239,"context_line":"   (see `Inferring Version`)"},{"line_number":240,"context_line":""},{"line_number":241,"context_line":"#. Determine if the ``{document-type}`` of the ``{discovery-document}`` is"},{"line_number":242,"context_line":"   ``single`` or ``multiple`` (see :ref:`single-or-multiple`)"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_6d4a0828","line":239,"range":{"start_line":239,"start_character":8,"end_line":239,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":250,"context_line":""},{"line_number":251,"context_line":"#. If there is no ``{endpoint-information}``, STOP. Infer the"},{"line_number":252,"context_line":"   ``{found-api-version}`` from ``{catalog-endpoint}``."},{"line_number":253,"context_line":"   (see `Inferring Version`)"},{"line_number":254,"context_line":""},{"line_number":255,"context_line":"#. STOP. Return the information in ``{endpoint-information}``. (see"},{"line_number":256,"context_line":"   :ref:`return-information`)."}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_0d5154d9","line":253,"range":{"start_line":253,"start_character":8,"end_line":253,"end_character":27},"updated":"2017-06-29 18:33:56.000000000","message":"ref","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":250,"context_line":""},{"line_number":251,"context_line":"#. If there is no ``{endpoint-information}``, STOP. Infer the"},{"line_number":252,"context_line":"   ``{found-api-version}`` from ``{catalog-endpoint}``."},{"line_number":253,"context_line":"   (see `Inferring Version`)"},{"line_number":254,"context_line":""},{"line_number":255,"context_line":"#. STOP. Return the information in ``{endpoint-information}``. (see"},{"line_number":256,"context_line":"   :ref:`return-information`)."}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_c118d176","line":253,"range":{"start_line":253,"start_character":8,"end_line":253,"end_character":27},"in_reply_to":"3f1d235d_0d5154d9","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":263,"context_line":""},{"line_number":264,"context_line":"The Unversioned Document is always preferred over the Versioned Document,"},{"line_number":265,"context_line":"becaues the Unversioned Document supplies the list of possible versions,"},{"line_number":266,"context_line":"allowing Discovery to process the list and make decisions in on step. The"},{"line_number":267,"context_line":"Versioned Document only contains one Version, so additional calls must be"},{"line_number":268,"context_line":"made if the version in it does not match the user\u0027s request."},{"line_number":269,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_eda058a8","line":266,"range":{"start_line":266,"start_character":61,"end_line":266,"end_character":63},"updated":"2017-06-29 18:33:56.000000000","message":"one","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":263,"context_line":""},{"line_number":264,"context_line":"The Unversioned Document is always preferred over the Versioned Document,"},{"line_number":265,"context_line":"becaues the Unversioned Document supplies the list of possible versions,"},{"line_number":266,"context_line":"allowing Discovery to process the list and make decisions in on step. The"},{"line_number":267,"context_line":"Versioned Document only contains one Version, so additional calls must be"},{"line_number":268,"context_line":"made if the version in it does not match the user\u0027s request."},{"line_number":269,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_812c199a","line":266,"range":{"start_line":266,"start_character":61,"end_line":266,"end_character":63},"in_reply_to":"3f1d235d_eda058a8","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":301,"context_line":""},{"line_number":302,"context_line":"For example:"},{"line_number":303,"context_line":""},{"line_number":304,"context_line":".. code-block:: python"},{"line_number":305,"context_line":""},{"line_number":306,"context_line":"  discovery_document \u003d {"},{"line_number":307,"context_line":"    \"versions\": ["}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_0d8f14cd","line":304,"range":{"start_line":304,"start_character":0,"end_line":304,"end_character":22},"updated":"2017-06-29 18:33:56.000000000","message":"It\u0027s not clear whether this block is an example, or the setup for the examples that follow.  L325-8 make it seem like the thing at L329+ is a result of applying the version discovery algorithm.  But the best I can infer is that the thing at L329+ is actually what happens when you GET http://compute.example.com, which you did because it was the thing with rel\u003dcollection in the thing at L306+ (and no idea where/how you GET that).  Otherwise there\u0027s no indication as to where the extra info in L329+ came from.\n\nBasically, /me confused.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":301,"context_line":""},{"line_number":302,"context_line":"For example:"},{"line_number":303,"context_line":""},{"line_number":304,"context_line":".. code-block:: python"},{"line_number":305,"context_line":""},{"line_number":306,"context_line":"  discovery_document \u003d {"},{"line_number":307,"context_line":"    \"versions\": ["}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_4104c17b","line":304,"range":{"start_line":304,"start_character":0,"end_line":304,"end_character":22},"in_reply_to":"3f1d235d_0d8f14cd","updated":"2017-07-12 15:30:44.000000000","message":"Fixed.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":322,"context_line":"    ]"},{"line_number":323,"context_line":"  }"},{"line_number":324,"context_line":""},{"line_number":325,"context_line":"  # collection link exists, use it"},{"line_number":326,"context_line":"  discovery_endpoint \u003d \"http://compute.example.com/\""},{"line_number":327,"context_line":""},{"line_number":328,"context_line":"  # New normalized document"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_0d4cb4c5","line":325,"range":{"start_line":325,"start_character":4,"end_line":325,"end_character":14},"updated":"2017-06-29 18:33:56.000000000","message":"First mention of this \u0027collection\u0027 thing; does this example belong further down?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":325,"context_line":"  # collection link exists, use it"},{"line_number":326,"context_line":"  discovery_endpoint \u003d \"http://compute.example.com/\""},{"line_number":327,"context_line":""},{"line_number":328,"context_line":"  # New normalized document"},{"line_number":329,"context_line":"  discovery_document \u003d {"},{"line_number":330,"context_line":"    \"versions\": ["},{"line_number":331,"context_line":"      {"},{"line_number":332,"context_line":"        \"status\": \"SUPPORTED\","},{"line_number":333,"context_line":"        \"links\": ["},{"line_number":334,"context_line":"          {"},{"line_number":335,"context_line":"            \"href\": \"http://compute.example.com/v2/\","},{"line_number":336,"context_line":"            \"rel\": \"self\""},{"line_number":337,"context_line":"          }"},{"line_number":338,"context_line":"        ],"},{"line_number":339,"context_line":"        \"min_version\": \"\","},{"line_number":340,"context_line":"        \"max_version\": \"\","},{"line_number":341,"context_line":"        \"id\": \"v2.0\""},{"line_number":342,"context_line":"      }, {"},{"line_number":343,"context_line":"        \"status\": \"CURRENT\","},{"line_number":344,"context_line":"        \"links\": ["},{"line_number":345,"context_line":"          {"},{"line_number":346,"context_line":"            \"href\": \"http://compute.example.com/v2.1/\","},{"line_number":347,"context_line":"            \"rel\": \"self\""},{"line_number":348,"context_line":"          }"},{"line_number":349,"context_line":"        ],"},{"line_number":350,"context_line":"        \"min_version\": \"2.1\","},{"line_number":351,"context_line":"        \"max_version\": \"2.38\","},{"line_number":352,"context_line":"        \"id\": \"v2.1\""},{"line_number":353,"context_line":"      }"},{"line_number":354,"context_line":"    ]"},{"line_number":355,"context_line":"  }"},{"line_number":356,"context_line":""},{"line_number":357,"context_line":"Example with project_id:"},{"line_number":358,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_2ddad016","line":355,"range":{"start_line":328,"start_character":0,"end_line":355,"end_character":3},"updated":"2017-06-29 18:33:56.000000000","message":"I don\u0027t get where this came from at all.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":364,"context_line":"  # GET catalog_endpoint returns 404"},{"line_number":365,"context_line":""},{"line_number":366,"context_line":"  # Pop project_id from catalog_endpoint"},{"line_number":367,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2\u0027"},{"line_number":368,"context_line":""},{"line_number":369,"context_line":"  # catalog_endpoint returns (normalized):"},{"line_number":370,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_8d3fa4d5","line":367,"range":{"start_line":367,"start_character":0,"end_line":367,"end_character":58},"updated":"2017-06-29 18:33:56.000000000","message":"L278-81 implies that we should further pop the \u0027v2\u0027 off of this before GETting it.  At least, that\u0027s how it reads to me.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":400,"context_line":"  # Pop project_id from catalog_endpoint"},{"line_number":401,"context_line":"  discovery_endpoint \u003d \u0027https://file-storage.example.com/v2\u0027"},{"line_number":402,"context_line":""},{"line_number":403,"context_line":"  # Pop version string from catalog endpoint"},{"line_number":404,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/\u0027"},{"line_number":405,"context_line":""},{"line_number":406,"context_line":"  return {"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_106047ce","line":403,"range":{"start_line":403,"start_character":28,"end_line":403,"end_character":44},"updated":"2017-06-29 18:33:56.000000000","message":"discovery_endpoint?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":470,"context_line":""},{"line_number":471,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":472,"context_line":"  # Match path elements - /v2/ matches ..."},{"line_number":473,"context_line":"  service_version \u003d \u00272\u0027"},{"line_number":474,"context_line":""},{"line_number":475,"context_line":"  catalog_endpoint \u003d \u0027https://identity-storage.example.com/\u0027"},{"line_number":476,"context_line":"  # Match path elements - no matches"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_f0d14b59","line":473,"range":{"start_line":473,"start_character":2,"end_line":473,"end_character":17},"updated":"2017-06-29 18:33:56.000000000","message":"found_api_version?  (This is the only mention of service_version in the document.)\n\nDitto x2 below.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":470,"context_line":""},{"line_number":471,"context_line":"  catalog_endpoint \u003d \u0027https://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":472,"context_line":"  # Match path elements - /v2/ matches ..."},{"line_number":473,"context_line":"  service_version \u003d \u00272\u0027"},{"line_number":474,"context_line":""},{"line_number":475,"context_line":"  catalog_endpoint \u003d \u0027https://identity-storage.example.com/\u0027"},{"line_number":476,"context_line":"  # Match path elements - no matches"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_012129b5","line":473,"range":{"start_line":473,"start_character":2,"end_line":473,"end_character":17},"in_reply_to":"3f1d235d_f0d14b59","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":478,"context_line":""},{"line_number":479,"context_line":"  catalog_endpoint \u003d \u0027https://object-store.example.com/v1/AUTH_622b11a1-5dfa-43b4-9f58-4ad3c6dbc4a0\u0027"},{"line_number":480,"context_line":"  # Match path elements - /v1/ matches ..."},{"line_number":481,"context_line":"  service_version \u003d \u00271\u0027"},{"line_number":482,"context_line":""},{"line_number":483,"context_line":".. _matching-endpoints:"},{"line_number":484,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_d009afdd","line":481,"range":{"start_line":481,"start_character":20,"end_line":481,"end_character":23},"updated":"2017-06-29 18:33:56.000000000","message":"Wouldn\u0027t mind an example with a vX.Y style version.  L455 implies that .../v3.2/... would result in \u00273.2\u0027 -- but then Comparing Major Versions kind of implies that .../v1/... should result in \u00271.0\u0027.  Where do those come together?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":478,"context_line":""},{"line_number":479,"context_line":"  catalog_endpoint \u003d \u0027https://object-store.example.com/v1/AUTH_622b11a1-5dfa-43b4-9f58-4ad3c6dbc4a0\u0027"},{"line_number":480,"context_line":"  # Match path elements - /v1/ matches ..."},{"line_number":481,"context_line":"  service_version \u003d \u00271\u0027"},{"line_number":482,"context_line":""},{"line_number":483,"context_line":".. _matching-endpoints:"},{"line_number":484,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_c5fe9c04","line":481,"range":{"start_line":481,"start_character":20,"end_line":481,"end_character":23},"in_reply_to":"3f1d235d_d009afdd","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":599,"context_line":"  joined_endpoint \u003d \u0027https://file-storage.example.com/v2.0\u0027"},{"line_number":600,"context_line":""},{"line_number":601,"context_line":"  # catalog_endpoint ends with project_id, append project_id"},{"line_number":602,"context_line":"  service_endpoint \u003d \u0027http://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":603,"context_line":""},{"line_number":604,"context_line":"With broken service endpoint in discovery:"},{"line_number":605,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_503b5f37","line":602,"range":{"start_line":602,"start_character":54,"end_line":602,"end_character":56},"updated":"2017-06-29 18:33:56.000000000","message":"Sorry, why does this not end up being v2.0?","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":599,"context_line":"  joined_endpoint \u003d \u0027https://file-storage.example.com/v2.0\u0027"},{"line_number":600,"context_line":""},{"line_number":601,"context_line":"  # catalog_endpoint ends with project_id, append project_id"},{"line_number":602,"context_line":"  service_endpoint \u003d \u0027http://file-storage.example.com/v2/45f0034e8c5a4ef4895b5a87b6b57def\u0027"},{"line_number":603,"context_line":""},{"line_number":604,"context_line":"With broken service endpoint in discovery:"},{"line_number":605,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_2538b0d1","line":602,"range":{"start_line":602,"start_character":54,"end_line":602,"end_character":56},"in_reply_to":"3f1d235d_503b5f37","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":660,"context_line":"In order to apply the discovery algorithm, the type of document must be"},{"line_number":661,"context_line":"detected."},{"line_number":662,"context_line":""},{"line_number":663,"context_line":"* If the document has a link description in the ``links`` list with a ``rel``"},{"line_number":664,"context_line":"  of ``collection`` and the ``href`` of that link is different than the"},{"line_number":665,"context_line":"  ``href`` of the link with a ``rel`` of ``self``, then it is a Single"},{"line_number":666,"context_line":"  Version Document."},{"line_number":667,"context_line":""},{"line_number":668,"context_line":"* Otherwise it is a Multiple Version Document and can be relied on to contain"},{"line_number":669,"context_line":"  the complete set of available versions."}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_50691f23","line":666,"range":{"start_line":663,"start_character":2,"end_line":666,"end_character":19},"updated":"2017-06-29 18:33:56.000000000","message":"Yeeeaahhh.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":660,"context_line":"In order to apply the discovery algorithm, the type of document must be"},{"line_number":661,"context_line":"detected."},{"line_number":662,"context_line":""},{"line_number":663,"context_line":"* If the document has a link description in the ``links`` list with a ``rel``"},{"line_number":664,"context_line":"  of ``collection`` and the ``href`` of that link is different than the"},{"line_number":665,"context_line":"  ``href`` of the link with a ``rel`` of ``self``, then it is a Single"},{"line_number":666,"context_line":"  Version Document."},{"line_number":667,"context_line":""},{"line_number":668,"context_line":"* Otherwise it is a Multiple Version Document and can be relied on to contain"},{"line_number":669,"context_line":"  the complete set of available versions."}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_e53198ee","line":666,"range":{"start_line":663,"start_character":2,"end_line":666,"end_character":19},"in_reply_to":"3f1d235d_50691f23","updated":"2017-07-12 15:30:44.000000000","message":"Tell me about it.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":667,"context_line":""},{"line_number":668,"context_line":"* Otherwise it is a Multiple Version Document and can be relied on to contain"},{"line_number":669,"context_line":"  the complete set of available versions."},{"line_number":670,"context_line":""},{"line_number":671,"context_line":".. _normalize-document:"},{"line_number":672,"context_line":""},{"line_number":673,"context_line":"Normalizing Documents"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_f0c6eb16","line":670,"updated":"2017-06-29 18:33:56.000000000","message":"Examples of the three possibilities (single, multiple-with-only-one, multiple-with-many) would go a long way here.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":667,"context_line":""},{"line_number":668,"context_line":"* Otherwise it is a Multiple Version Document and can be relied on to contain"},{"line_number":669,"context_line":"  the complete set of available versions."},{"line_number":670,"context_line":""},{"line_number":671,"context_line":".. _normalize-document:"},{"line_number":672,"context_line":""},{"line_number":673,"context_line":"Normalizing Documents"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_253d50bb","line":670,"in_reply_to":"3f1d235d_f0c6eb16","updated":"2017-07-12 15:30:44.000000000","message":"Agree. Will make a note to follow up.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":698,"context_line":"    \"versions\": {"},{"line_number":699,"context_line":"      \"values\": ["},{"line_number":700,"context_line":"        {"},{"line_number":701,"context_line":"          \"status\": \"stable\","},{"line_number":702,"context_line":"          \"updated\": \"2016-10-06T00:00:00Z\","},{"line_number":703,"context_line":"          \"media-types\": ["},{"line_number":704,"context_line":"            {"},{"line_number":705,"context_line":"              \"base\": \"application/json\","},{"line_number":706,"context_line":"              \"type\": \"application/vnd.openstack.identity-v3+json\""},{"line_number":707,"context_line":"            }"},{"line_number":708,"context_line":"          ],"},{"line_number":709,"context_line":"          \"id\": \"v3.7\","},{"line_number":710,"context_line":"          \"links\": ["},{"line_number":711,"context_line":"            {"},{"line_number":712,"context_line":"              \"href\": \"https://auth.example.com/v3/\","},{"line_number":713,"context_line":"              \"rel\": \"self\""},{"line_number":714,"context_line":"            }"},{"line_number":715,"context_line":"          ]"},{"line_number":716,"context_line":"        },"},{"line_number":717,"context_line":"        {"},{"line_number":718,"context_line":"          \"status\": \"deprecated\","}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_d0676f25","line":715,"range":{"start_line":701,"start_character":0,"end_line":715,"end_character":11},"updated":"2017-06-29 18:33:56.000000000","message":"For readability, you could elide these guts (here and below) since they\u0027re not relevant to the example.","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":698,"context_line":"    \"versions\": {"},{"line_number":699,"context_line":"      \"values\": ["},{"line_number":700,"context_line":"        {"},{"line_number":701,"context_line":"          \"status\": \"stable\","},{"line_number":702,"context_line":"          \"updated\": \"2016-10-06T00:00:00Z\","},{"line_number":703,"context_line":"          \"media-types\": ["},{"line_number":704,"context_line":"            {"},{"line_number":705,"context_line":"              \"base\": \"application/json\","},{"line_number":706,"context_line":"              \"type\": \"application/vnd.openstack.identity-v3+json\""},{"line_number":707,"context_line":"            }"},{"line_number":708,"context_line":"          ],"},{"line_number":709,"context_line":"          \"id\": \"v3.7\","},{"line_number":710,"context_line":"          \"links\": ["},{"line_number":711,"context_line":"            {"},{"line_number":712,"context_line":"              \"href\": \"https://auth.example.com/v3/\","},{"line_number":713,"context_line":"              \"rel\": \"self\""},{"line_number":714,"context_line":"            }"},{"line_number":715,"context_line":"          ]"},{"line_number":716,"context_line":"        },"},{"line_number":717,"context_line":"        {"},{"line_number":718,"context_line":"          \"status\": \"deprecated\","}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_25ab10d7","line":715,"range":{"start_line":701,"start_character":0,"end_line":715,"end_character":11},"in_reply_to":"3f1d235d_d0676f25","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1030,"context_line":"        \"min_version\": \"\","},{"line_number":1031,"context_line":"        \"version\": \"\","},{"line_number":1032,"context_line":"        \"id\": \"v2.0\""},{"line_number":1033,"context_line":"      }, {"},{"line_number":1034,"context_line":"        \"status\": \"CURRENT\","},{"line_number":1035,"context_line":"        \"updated\": \"2013-07-23T11:33:21Z\","},{"line_number":1036,"context_line":"        \"links\": ["}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_e32747b6","line":1033,"range":{"start_line":1033,"start_character":6,"end_line":1033,"end_character":10},"updated":"2017-06-29 18:33:56.000000000","message":"\\n (for consistency with other examples)","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1030,"context_line":"        \"min_version\": \"\","},{"line_number":1031,"context_line":"        \"version\": \"\","},{"line_number":1032,"context_line":"        \"id\": \"v2.0\""},{"line_number":1033,"context_line":"      }, {"},{"line_number":1034,"context_line":"        \"status\": \"CURRENT\","},{"line_number":1035,"context_line":"        \"updated\": \"2013-07-23T11:33:21Z\","},{"line_number":1036,"context_line":"        \"links\": ["}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_a5d6004f","line":1033,"range":{"start_line":1033,"start_character":6,"end_line":1033,"end_character":10},"in_reply_to":"3f1d235d_e32747b6","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1063,"context_line":"        \"min_version\": \"\","},{"line_number":1064,"context_line":"        \"max_version\": \"\","},{"line_number":1065,"context_line":"        \"id\": \"v2.0\""},{"line_number":1066,"context_line":"      }, {"},{"line_number":1067,"context_line":"        \"status\": \"CURRENT\","},{"line_number":1068,"context_line":"        \"links\": ["},{"line_number":1069,"context_line":"          {"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_c32c4b9b","line":1066,"range":{"start_line":1066,"start_character":6,"end_line":1066,"end_character":10},"updated":"2017-06-29 18:33:56.000000000","message":"ditto","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1063,"context_line":"        \"min_version\": \"\","},{"line_number":1064,"context_line":"        \"max_version\": \"\","},{"line_number":1065,"context_line":"        \"id\": \"v2.0\""},{"line_number":1066,"context_line":"      }, {"},{"line_number":1067,"context_line":"        \"status\": \"CURRENT\","},{"line_number":1068,"context_line":"        \"links\": ["},{"line_number":1069,"context_line":"          {"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_25c2f086","line":1066,"range":{"start_line":1066,"start_character":6,"end_line":1066,"end_character":10},"in_reply_to":"3f1d235d_c32c4b9b","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1085,"context_line":"``{api-version}`` with the ``id`` field of the description to find a list"},{"line_number":1086,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1087,"context_line":""},{"line_number":1088,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_4394bb8b","line":1088,"range":{"start_line":1088,"start_character":9,"end_line":1088,"end_character":46},"updated":"2017-06-29 18:33:56.000000000","message":"\"is ... that matches\"","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1085,"context_line":"``{api-version}`` with the ``id`` field of the description to find a list"},{"line_number":1086,"context_line":"of ``{candidate-endpoints}``. (see: `Comparing Major Versions`_)"},{"line_number":1087,"context_line":""},{"line_number":1088,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_e55078d7","line":1088,"range":{"start_line":1088,"start_character":9,"end_line":1088,"end_character":46},"in_reply_to":"3f1d235d_4394bb8b","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1088,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_a3f26f05","line":1091,"range":{"start_line":1091,"start_character":9,"end_line":1091,"end_character":46},"updated":"2017-06-29 18:33:56.000000000","message":"ditto","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1088,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_c55fbce3","line":1091,"range":{"start_line":1091,"start_character":9,"end_line":1091,"end_character":46},"in_reply_to":"3f1d235d_a3f26f05","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1095,"context_line":"and more than one has the ``status`` of ``CURRENT``, the highest should be"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_63dc5774","line":1092,"range":{"start_line":1092,"start_character":9,"end_line":1092,"end_character":13},"updated":"2017-06-29 18:33:56.000000000","message":"has","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1089,"context_line":"and one of them has ``status`` of ``CURRENT``, it should be returned."},{"line_number":1090,"context_line":""},{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1095,"context_line":"and more than one has the ``status`` of ``CURRENT``, the highest should be"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_8559c4ff","line":1092,"range":{"start_line":1092,"start_character":9,"end_line":1092,"end_character":13},"in_reply_to":"3f1d235d_63dc5774","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1095,"context_line":"and more than one has the ``status`` of ``CURRENT``, the highest should be"},{"line_number":1096,"context_line":"returned."},{"line_number":1097,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_03e36335","line":1094,"range":{"start_line":1094,"start_character":9,"end_line":1094,"end_character":46},"updated":"2017-06-29 18:33:56.000000000","message":"ditto","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1091,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1092,"context_line":"and none have the ``status`` of ``CURRENT``, the highest should be returned."},{"line_number":1093,"context_line":""},{"line_number":1094,"context_line":"If there are more than one ``{id}`` that match the requested ``{api-version}``"},{"line_number":1095,"context_line":"and more than one has the ``status`` of ``CURRENT``, the highest should be"},{"line_number":1096,"context_line":"returned."},{"line_number":1097,"context_line":""}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_655ea8e7","line":1094,"range":{"start_line":1094,"start_character":9,"end_line":1094,"end_character":46},"in_reply_to":"3f1d235d_03e36335","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1102,"context_line":""},{"line_number":1103,"context_line":"When comparing Major Versions, there is a ``required`` and a ``candidate``."},{"line_number":1104,"context_line":"The ``required`` is what the user has requested."},{"line_number":1105,"context_line":"The ``candidate`` is what the possible version being tested."},{"line_number":1106,"context_line":""},{"line_number":1107,"context_line":"To be suitable a ``candidate`` must be of the same major version as"},{"line_number":1108,"context_line":"``required`` and be at least a match in minor level: ``candidate`` ``3.3``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_83d09352","line":1105,"range":{"start_line":1105,"start_character":21,"end_line":1105,"end_character":25},"updated":"2017-06-29 18:33:56.000000000","message":"strike","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1102,"context_line":""},{"line_number":1103,"context_line":"When comparing Major Versions, there is a ``required`` and a ``candidate``."},{"line_number":1104,"context_line":"The ``required`` is what the user has requested."},{"line_number":1105,"context_line":"The ``candidate`` is what the possible version being tested."},{"line_number":1106,"context_line":""},{"line_number":1107,"context_line":"To be suitable a ``candidate`` must be of the same major version as"},{"line_number":1108,"context_line":"``required`` and be at least a match in minor level: ``candidate`` ``3.3``"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_4573ac81","line":1105,"range":{"start_line":1105,"start_character":21,"end_line":1105,"end_character":25},"in_reply_to":"3f1d235d_83d09352","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"3b6590ae8c40579e4e44c93699d151710c03ca57","unresolved":false,"context_lines":[{"line_number":1135,"context_line":"If one of the versions in the list has ``status`` of ``CURRENT``, use it."},{"line_number":1136,"context_line":""},{"line_number":1137,"context_line":"Otherwise, select the version with the highest ``id``, excluding any with"},{"line_number":1138,"context_line":"``status`` of ``EXPERIMENTAL`` sorted using version comparison not lexical"},{"line_number":1139,"context_line":"sorting."},{"line_number":1140,"context_line":""},{"line_number":1141,"context_line":".. _return-information:"}],"source_content_type":"text/x-rst","patch_set":26,"id":"3f1d235d_a3594fff","line":1138,"range":{"start_line":1138,"start_character":16,"end_line":1138,"end_character":28},"updated":"2017-06-29 18:33:56.000000000","message":"or DEPRECATED? (Which maybe should never happen, but I would think should be accounted for anyway.)","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"04f9a97fc83158077d7bf9b727d2e03b2d228874","unresolved":false,"context_lines":[{"line_number":1135,"context_line":"If one of the versions in the list has ``status`` of ``CURRENT``, use it."},{"line_number":1136,"context_line":""},{"line_number":1137,"context_line":"Otherwise, select the version with the highest ``id``, excluding any with"},{"line_number":1138,"context_line":"``status`` of ``EXPERIMENTAL`` sorted using version comparison not lexical"},{"line_number":1139,"context_line":"sorting."},{"line_number":1140,"context_line":""},{"line_number":1141,"context_line":".. _return-information:"}],"source_content_type":"text/x-rst","patch_set":26,"id":"1f1a1f67_e569988b","line":1138,"range":{"start_line":1138,"start_character":16,"end_line":1138,"end_character":28},"in_reply_to":"3f1d235d_a3594fff","updated":"2017-07-12 15:30:44.000000000","message":"Done","commit_id":"54e79a875aba7f2b38a1e824dedcdf423e515463"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":28,"id":"7f515b1d_a2dfce0a","updated":"2017-10-05 13:11:18.000000000","message":"I wonder about the split between the two documents: consuming-catalog and consuming-version-discovery. You talk about versions in consuming-catalog in the end.. I wonder if it\u0027s better be one (huge and exciting) document..","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0a1490f4a48a3a43e1a6d44ffe47e7f57e47e9ba","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":28,"id":"7f96bb07_11ce5762","in_reply_to":"7f515b1d_690d363d","updated":"2018-01-18 15:20:32.000000000","message":"+1 on combining","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":28,"id":"7f515b1d_690d363d","in_reply_to":"7f515b1d_a2dfce0a","updated":"2017-10-05 16:28:48.000000000","message":"That\u0027s probably not a bad idea at all. I can followup the stack with a re-org.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":496,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":497,"context_line":""},{"line_number":498,"context_line":"#. If the endpoint ends with a path element that ends with ``project_id``,"},{"line_number":499,"context_line":"   remove it."},{"line_number":500,"context_line":""},{"line_number":501,"context_line":"#. If the endpoint ends with a path element that is of the form,"},{"line_number":502,"context_line":"   \"^v[0-9]+(\\.[0-9]+)?$\", strip the v and use the rest of that element as"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_82e612e8","line":499,"updated":"2017-10-05 13:11:18.000000000","message":"side note: can we just ban doing this for greater good please? I got some gray hair figuring out this particular bit while working on rust-openstack..","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":496,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":497,"context_line":""},{"line_number":498,"context_line":"#. If the endpoint ends with a path element that ends with ``project_id``,"},{"line_number":499,"context_line":"   remove it."},{"line_number":500,"context_line":""},{"line_number":501,"context_line":"#. If the endpoint ends with a path element that is of the form,"},{"line_number":502,"context_line":"   \"^v[0-9]+(\\.[0-9]+)?$\", strip the v and use the rest of that element as"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_440dbf33","line":499,"in_reply_to":"7f515b1d_82e612e8","updated":"2017-10-05 16:28:48.000000000","message":"a) YOU HAVE A RUST-OPENSTACK I WANT TO PLAY\n\nb) we can and should moving forward - but it\u0027s still out there and clients need to support it.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":530,"context_line":""},{"line_number":531,"context_line":"  catalog_endpoint \u003d \u0027https://compute.example.com/v2.1\u0027"},{"line_number":532,"context_line":"  # Match path elements - /v2.1/ matches ..."},{"line_number":533,"context_line":"  found_api_version \u003d \u00272.1\u0027"},{"line_number":534,"context_line":""},{"line_number":535,"context_line":".. _matching-endpoints:"},{"line_number":536,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_62e9d6b5","line":533,"updated":"2017-10-05 13:11:18.000000000","message":"This is the point when I got finally confused about api_version references here. Is it a major or a micro version? If it\u0027s a microversion, it\u0027s probably incorrect.\n\nOkay, imagine an Application requests Compute versions [\u00272.1\u0027 or [\u00272.10\u0027] (as I said above, I don\u0027t like using ranges here). The maximum microversion is \u00272.20\u0027, but the discovery process gets to this point and ends up with \u00272.1\u0027? This does not look correct, which brings us back to my point that fetch-endpoint-version has to be True.\n\nOr maybe I\u0027m finally and utterly confused.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":530,"context_line":""},{"line_number":531,"context_line":"  catalog_endpoint \u003d \u0027https://compute.example.com/v2.1\u0027"},{"line_number":532,"context_line":"  # Match path elements - /v2.1/ matches ..."},{"line_number":533,"context_line":"  found_api_version \u003d \u00272.1\u0027"},{"line_number":534,"context_line":""},{"line_number":535,"context_line":".. _matching-endpoints:"},{"line_number":536,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_244ac354","line":533,"in_reply_to":"7f515b1d_62e9d6b5","updated":"2017-10-05 16:28:48.000000000","message":"api_version is always a major version.\n\nOne of the most important points that needs to be added somewhere is that finding major api version endpoint is about finding the endpoint to use from the catalog and version discovery. Microversions, on the other hand, are attributes of that major-versioned api endpoint - and should be applied on a request-by-request basis. So you need to find your endpoint for your connection, but then as you make calls you need to have the information to be able to decide which microversion, if any, you will request for that call.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"2bbb84b077dac1610f48a0aad822c621d47e316c","unresolved":false,"context_lines":[{"line_number":594,"context_line":"#. Replace the ``scheme`` and ``host`` of the endpoint from the discovery"},{"line_number":595,"context_line":"   document with the ``scheme`` and ``host`` from the endpoint it was fetched"},{"line_number":596,"context_line":"   from. This is to work around older buggy discovery documents seen in the"},{"line_number":597,"context_line":"   wild."},{"line_number":598,"context_line":""},{"line_number":599,"context_line":"   For example:"},{"line_number":600,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_42d01af8","line":597,"updated":"2017-10-05 13:11:18.000000000","message":"++ got me some gray hair too","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"b24f2fe436ce5da67d0f88293283044666228000","unresolved":false,"context_lines":[{"line_number":594,"context_line":"#. Replace the ``scheme`` and ``host`` of the endpoint from the discovery"},{"line_number":595,"context_line":"   document with the ``scheme`` and ``host`` from the endpoint it was fetched"},{"line_number":596,"context_line":"   from. This is to work around older buggy discovery documents seen in the"},{"line_number":597,"context_line":"   wild."},{"line_number":598,"context_line":""},{"line_number":599,"context_line":"   For example:"},{"line_number":600,"context_line":""}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f515b1d_a46fd3c3","line":597,"in_reply_to":"7f515b1d_42d01af8","updated":"2017-10-05 16:28:48.000000000","message":"Yah. tell me about it.","commit_id":"cd26843a47f02886faa116705d73589834aa5370"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0a1490f4a48a3a43e1a6d44ffe47e7f57e47e9ba","unresolved":false,"context_lines":[{"line_number":727,"context_line":"Normalizing Documents"},{"line_number":728,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":729,"context_line":""},{"line_number":730,"context_line":".. note:: If the API-WG recommendations in :ref:`discoverability`"},{"line_number":731,"context_line":"          are implemented, all of the logic in this section can be skipped."},{"line_number":732,"context_line":""},{"line_number":733,"context_line":"There are three forms of existing version discovery documents in addition to"}],"source_content_type":"text/x-rst","patch_set":28,"id":"7f96bb07_d12c6fad","line":730,"range":{"start_line":730,"start_character":17,"end_line":730,"end_character":23},"updated":"2018-01-18 15:20:32.000000000","message":"SIG","commit_id":"cd26843a47f02886faa116705d73589834aa5370"}]}