)]}'
{"doc/source/discovery.rst":[{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1f7cc4ca2540ceebf24ba1ae998b23e772335d98","unresolved":false,"context_lines":[{"line_number":15,"context_line":"For any given service, there are two optional values a user can provide,"},{"line_number":16,"context_line":"``{service}_api_version`` and ``{service}_endpoint_override`` - where service"},{"line_number":17,"context_line":"is the ``service_type`` value, such as ``compute``, ``image`` or"},{"line_number":18,"context_line":"``file-storage``. It is expected that shade will figure out and do the right"},{"line_number":19,"context_line":"thing in the absence of either value and that they should only be needed in"},{"line_number":20,"context_line":"exceptional cases."},{"line_number":21,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_231fdeb7","line":18,"range":{"start_line":18,"start_character":18,"end_line":18,"end_character":48},"updated":"2017-04-20 19:16:48.000000000","message":"This seems more general than just shade - ideally it should affect all of OpenStack\u0027s APIs. Can you make the shade references generic, and then propose it to the API WG? We already have a placeholder for it: https://specs.openstack.org/openstack/api-wg/guidelines/discoverability.html","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a9447c356e2daebc4e9380fa3996b6e4f350c2be","unresolved":false,"context_lines":[{"line_number":15,"context_line":"For any given service, there are two optional values a user can provide,"},{"line_number":16,"context_line":"``{service}_api_version`` and ``{service}_endpoint_override`` - where service"},{"line_number":17,"context_line":"is the ``service_type`` value, such as ``compute``, ``image`` or"},{"line_number":18,"context_line":"``file-storage``. It is expected that shade will figure out and do the right"},{"line_number":19,"context_line":"thing in the absence of either value and that they should only be needed in"},{"line_number":20,"context_line":"exceptional cases."},{"line_number":21,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_e0f436f3","line":18,"range":{"start_line":18,"start_character":18,"end_line":18,"end_character":48},"in_reply_to":"7ffa3b31_231fdeb7","updated":"2017-04-21 11:42:58.000000000","message":"Cool - can do! I think there may be three things this might ultimately want to split into:\n\na) how discoveability _should_ work in the future.\nb) how clients must consume discovery today\nc) any shade-specific amendments to (b)\n\nThis is obviously a combo of b and c right now - but I can totally work on making it a good generic b with examples and then figure out what, if any, shade-specific logic is listed.\n\nI can also write A, which will be fun. It turns out A, written in the context of this, can show \"for clouds/services that properly implement discovery guidelines, look at how many fewer calls the client has to make\"","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":15,"context_line":"For any given service, there are two optional values a user can provide,"},{"line_number":16,"context_line":"``{service}_api_version`` and ``{service}_endpoint_override`` - where service"},{"line_number":17,"context_line":"is the ``service_type`` value, such as ``compute``, ``image`` or"},{"line_number":18,"context_line":"``file-storage``. It is expected that shade will figure out and do the right"},{"line_number":19,"context_line":"thing in the absence of either value and that they should only be needed in"},{"line_number":20,"context_line":"exceptional cases."},{"line_number":21,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_ed842ed5","line":18,"in_reply_to":"7ffa3b31_e0f436f3","updated":"2017-04-21 13:05:18.000000000","message":"++++++++ for A, that also highlights why I want a single version doc to come with (part of or parallel to) the service catalog from Keystone","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1f7cc4ca2540ceebf24ba1ae998b23e772335d98","unresolved":false,"context_lines":[{"line_number":52,"context_line":"   is a multiple version document, and there is a match in the document for"},{"line_number":53,"context_line":"   the version requested, use that endpoint."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document"},{"line_number":56,"context_line":"   is a multiple version document, and there is not an endpoint in the"},{"line_number":57,"context_line":"   document for the version requested, find the endpoint in the document that"},{"line_number":58,"context_line":"   matches the endpoint from the catalog and use it, so that version will be"},{"line_number":59,"context_line":"   known.  (see :ref:`matching-endpoints`) If no endpoint matches, use the"},{"line_number":60,"context_line":"   catalog endpoint and infer the api version (see :ref:`inferring-version`)"},{"line_number":61,"context_line":""},{"line_number":62,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document is a"},{"line_number":63,"context_line":"   single version document and the version in the document matches the provided"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_23747efd","line":60,"range":{"start_line":55,"start_character":0,"end_line":60,"end_character":76},"updated":"2017-04-20 19:16:48.000000000","message":"I made it about halfway through before getting lost. Maybe create example URLs and docs to show each of these conditions? Sorry, I\u0027m more visual.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a9447c356e2daebc4e9380fa3996b6e4f350c2be","unresolved":false,"context_lines":[{"line_number":52,"context_line":"   is a multiple version document, and there is a match in the document for"},{"line_number":53,"context_line":"   the version requested, use that endpoint."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document"},{"line_number":56,"context_line":"   is a multiple version document, and there is not an endpoint in the"},{"line_number":57,"context_line":"   document for the version requested, find the endpoint in the document that"},{"line_number":58,"context_line":"   matches the endpoint from the catalog and use it, so that version will be"},{"line_number":59,"context_line":"   known.  (see :ref:`matching-endpoints`) If no endpoint matches, use the"},{"line_number":60,"context_line":"   catalog endpoint and infer the api version (see :ref:`inferring-version`)"},{"line_number":61,"context_line":""},{"line_number":62,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document is a"},{"line_number":63,"context_line":"   single version document and the version in the document matches the provided"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_602f0688","line":60,"range":{"start_line":55,"start_character":0,"end_line":60,"end_character":76},"in_reply_to":"7ffa3b31_23747efd","updated":"2017-04-21 11:42:58.000000000","message":"Totally.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"8d6684014092fb9b14c8e941f7bba6e2d3ca4082","unresolved":false,"context_lines":[{"line_number":52,"context_line":"   is a multiple version document, and there is a match in the document for"},{"line_number":53,"context_line":"   the version requested, use that endpoint."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document"},{"line_number":56,"context_line":"   is a multiple version document, and there is not an endpoint in the"},{"line_number":57,"context_line":"   document for the version requested, find the endpoint in the document that"},{"line_number":58,"context_line":"   matches the endpoint from the catalog and use it, so that version will be"},{"line_number":59,"context_line":"   known.  (see :ref:`matching-endpoints`) If no endpoint matches, use the"},{"line_number":60,"context_line":"   catalog endpoint and infer the api version (see :ref:`inferring-version`)"},{"line_number":61,"context_line":""},{"line_number":62,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document is a"},{"line_number":63,"context_line":"   single version document and the version in the document matches the provided"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_b52af2d7","line":60,"range":{"start_line":55,"start_character":0,"end_line":60,"end_character":76},"in_reply_to":"7ffa3b31_23747efd","updated":"2017-04-21 11:36:17.000000000","message":"versioned/unversioned x version provided/not provided could also be a table, making it easier to understand all the cases.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a9447c356e2daebc4e9380fa3996b6e4f350c2be","unresolved":false,"context_lines":[{"line_number":52,"context_line":"   is a multiple version document, and there is a match in the document for"},{"line_number":53,"context_line":"   the version requested, use that endpoint."},{"line_number":54,"context_line":""},{"line_number":55,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document"},{"line_number":56,"context_line":"   is a multiple version document, and there is not an endpoint in the"},{"line_number":57,"context_line":"   document for the version requested, find the endpoint in the document that"},{"line_number":58,"context_line":"   matches the endpoint from the catalog and use it, so that version will be"},{"line_number":59,"context_line":"   known.  (see :ref:`matching-endpoints`) If no endpoint matches, use the"},{"line_number":60,"context_line":"   catalog endpoint and infer the api version (see :ref:`inferring-version`)"},{"line_number":61,"context_line":""},{"line_number":62,"context_line":"#. If ``{service}_api_version`` is provided and the discovery document is a"},{"line_number":63,"context_line":"   single version document and the version in the document matches the provided"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_80be92fc","line":60,"range":{"start_line":55,"start_character":0,"end_line":60,"end_character":76},"in_reply_to":"7ffa3b31_b52af2d7","updated":"2017-04-21 11:42:58.000000000","message":"Nod.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"8d6684014092fb9b14c8e941f7bba6e2d3ca4082","unresolved":false,"context_lines":[{"line_number":84,"context_line":"   \"v[0-9]+.*\", pop that element from the end of the endpoint and return"},{"line_number":85,"context_line":"   to discovery with this new endpoint."},{"line_number":86,"context_line":""},{"line_number":87,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_357ca2ea","line":87,"range":{"start_line":87,"start_character":11,"end_line":87,"end_character":19},"updated":"2017-04-21 11:36:17.000000000","message":"(nit) currently","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"8d6684014092fb9b14c8e941f7bba6e2d3ca4082","unresolved":false,"context_lines":[{"line_number":84,"context_line":"   \"v[0-9]+.*\", pop that element from the end of the endpoint and return"},{"line_number":85,"context_line":"   to discovery with this new endpoint."},{"line_number":86,"context_line":""},{"line_number":87,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_d5eb3e75","line":87,"range":{"start_line":87,"start_character":0,"end_line":87,"end_character":2},"updated":"2017-04-21 11:36:17.000000000","message":"where is this useful here in this section \"find a document\" ?","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a9447c356e2daebc4e9380fa3996b6e4f350c2be","unresolved":false,"context_lines":[{"line_number":84,"context_line":"   \"v[0-9]+.*\", pop that element from the end of the endpoint and return"},{"line_number":85,"context_line":"   to discovery with this new endpoint."},{"line_number":86,"context_line":""},{"line_number":87,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_e05b16f3","line":87,"range":{"start_line":87,"start_character":0,"end_line":87,"end_character":2},"in_reply_to":"7ffa3b31_d5eb3e75","updated":"2017-04-21 11:42:58.000000000","message":"You need it for the next step - you can\u0027t test to see if the endpoint ends in project_id if you don\u0027t have project_id.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"},{"line_number":91,"context_line":"   so for later. Return to discovery with this new endpoint."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"#. If no new endpoint can be found, then return to discovery reporting no"},{"line_number":94,"context_line":"   working discovery document."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_6053863a","line":91,"updated":"2017-04-21 13:05:18.000000000","message":"Is this return recursive?  ie, compute could be /v2.0/\u003cproject-id\u003e so you may need a second pass through the find-document to pop the version after popping the project id.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"8d6684014092fb9b14c8e941f7bba6e2d3ca4082","unresolved":false,"context_lines":[{"line_number":87,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"},{"line_number":91,"context_line":"   so for later. Return to discovery with this new endpoint."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"#. If no new endpoint can be found, then return to discovery reporting no"},{"line_number":94,"context_line":"   working discovery document."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_956a5617","line":91,"range":{"start_line":90,"start_character":47,"end_line":91,"end_character":15},"updated":"2017-04-21 11:36:17.000000000","message":"what type of note and what will this useful for?","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"a9447c356e2daebc4e9380fa3996b6e4f350c2be","unresolved":false,"context_lines":[{"line_number":87,"context_line":"#. Get the curently scoped ``project_id`` from the token, if one exists."},{"line_number":88,"context_line":""},{"line_number":89,"context_line":"#. If the current discovery endpoint ends with the ``project_id``, pop the"},{"line_number":90,"context_line":"   ``project_id`` from the end of the endpoint but make a note of having done"},{"line_number":91,"context_line":"   so for later. Return to discovery with this new endpoint."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"#. If no new endpoint can be found, then return to discovery reporting no"},{"line_number":94,"context_line":"   working discovery document."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_c0fb7abe","line":91,"range":{"start_line":90,"start_character":47,"end_line":91,"end_character":15},"in_reply_to":"7ffa3b31_956a5617","updated":"2017-04-21 11:42:58.000000000","message":"You\u0027ll need it in the normalization step.\n\nThanks - I\u0027ll make a note of both things.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":17860,"name":"Samuel de Medeiros Queiroz","email":"samueldmq@gmail.com","username":"samueldmq"},"change_message_id":"8d6684014092fb9b14c8e941f7bba6e2d3ca4082","unresolved":false,"context_lines":[{"line_number":98,"context_line":"Inferring Version"},{"line_number":99,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"In most cases the version of the endpoint should be retreivable from the"},{"line_number":102,"context_line":"version discovery document, and in those cases it should be considered the"},{"line_number":103,"context_line":"version of the service at the endpoint. There are two cases where a version"},{"line_number":104,"context_line":"must be inferred with only the endpoint to go on:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_1568861a","line":101,"range":{"start_line":101,"start_character":52,"end_line":101,"end_character":63},"updated":"2017-04-21 11:36:17.000000000","message":"(nit) retrievable","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":149,"context_line":""},{"line_number":150,"context_line":"#. If the endpoint from the discovery document is relative, join it with the"},{"line_number":151,"context_line":"   endpoint that the discovery document was fetched from."},{"line_number":152,"context_line":"   ``six.moves.urllib.parse.urljoin`` does the right thing and can be used"},{"line_number":153,"context_line":"   unconditionally."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"#. Replace the ``scheme`` of the endpoint from the discovery document with"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_7b90db95","line":152,"updated":"2017-04-21 13:05:18.000000000","message":"We should make sure to be specific about what \u0027the right thing\u0027 is somewhere so other languages can join in on this fun","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":152,"context_line":"   ``six.moves.urllib.parse.urljoin`` does the right thing and can be used"},{"line_number":153,"context_line":"   unconditionally."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"#. Replace the ``scheme`` of the endpoint from the discovery document with"},{"line_number":156,"context_line":"   the ``scheme`` from the endpoint it was fetched from. This is because"},{"line_number":157,"context_line":"   some services have buggy discovery documents that return incorrect schemes."},{"line_number":158,"context_line":"   For example:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_2d31f65a","line":155,"updated":"2017-04-21 13:05:18.000000000","message":"At one time OSC also did this for the host in the endpoint when the catalog contained \u0027localhost\u0027 due to an early Keystone default config value that was seen in the wild.  I don\u0027t think we need to continue that today, or is it handled in the \u0027right thing\u0027 in the line 150 point?","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":217,"context_line":""},{"line_number":218,"context_line":"#. If there is a ``version`` field and not a ``min_version`` field, make a"},{"line_number":219,"context_line":"   ``min_version`` field with the value from the ``version`` field. (handles"},{"line_number":220,"context_line":"   nova microversions)"},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"#. Keys other than ``id``, ``min_version``, ``max_version``, ``status`` and"},{"line_number":223,"context_line":"   ``links`` can be ignored or removed."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_cd24d260","line":220,"updated":"2017-04-21 13:05:18.000000000","message":"I _think_ this would also let the microversion code seamlessly handle non-microversioned APIs without needing special cases.  Although for defensive reasons we should probably do both.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"30dcbe77578eb860886876449e672bd502dd7903","unresolved":false,"context_lines":[{"line_number":219,"context_line":"   ``min_version`` field with the value from the ``version`` field. (handles"},{"line_number":220,"context_line":"   nova microversions)"},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"#. Keys other than ``id``, ``min_version``, ``max_version``, ``status`` and"},{"line_number":223,"context_line":"   ``links`` can be ignored or removed."},{"line_number":224,"context_line":""},{"line_number":225,"context_line":"#. The ``links`` key should contain a list, and that list should contain one"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7ffa3b31_4dd6822a","line":222,"updated":"2017-04-21 13:05:18.000000000","message":"Move this to the top of this list to set the scope of fields we care about.","commit_id":"93145e0df58a07bff87101fd09badba0f69e8e50"}]}