)]}'
{"guidelines/sdk-exposing-microversions.rst":[{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1e32dd8e5a8e133054de7886ec3cfe505803abc9","unresolved":false,"context_lines":[{"line_number":15,"context_line":"* `Low-level SDK`_ is one closely following the structure and design of the"},{"line_number":16,"context_line":"  underlying API. Such SDKs usually try to build as little additional"},{"line_number":17,"context_line":"  abstraction layers on top of the underlying API as possible. Examples"},{"line_number":18,"context_line":"  include all standard OpenStack ``python-\u003cservice-name\u003eclient`` libraries."},{"line_number":19,"context_line":""},{"line_number":20,"context_line":"* `High-level SDK`_ is one that hides details of the underlying API from"},{"line_number":21,"context_line":"  consumers, building its own abstraction layers. Its approach to backward and"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7f96bb07_4cd092f8","line":18,"range":{"start_line":18,"start_character":14,"end_line":18,"end_character":22},"updated":"2018-01-11 13:43:51.000000000","message":"Is \"standard\" a safe word in this context. There are plenty of reasons to avoid those clients...\n\nThey are a good example of not having a lot of abstraction, but I\u0027m not sure we should present them as standard.","commit_id":"df9e37a54ff23fbc3fa47407aecd6ece7d52cbeb"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1e32dd8e5a8e133054de7886ec3cfe505803abc9","unresolved":false,"context_lines":[{"line_number":24,"context_line":"  OpenStack."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"For the purpose of this document we will call *application* or *consumer*"},{"line_number":27,"context_line":"a programming code interfacing with an SDK. We will use the Python programming"},{"line_number":28,"context_line":"language in all examples, but the recommendations will apply to any"},{"line_number":29,"context_line":"programming languages, including statically compiled ones."},{"line_number":30,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"7f96bb07_ac04b67c","line":27,"updated":"2018-01-11 13:43:51.000000000","message":"word missing from this first sentence?","commit_id":"df9e37a54ff23fbc3fa47407aecd6ece7d52cbeb"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"242ae4e64b791fc596b13c71077014e6aa0480dd","unresolved":false,"context_lines":[{"line_number":37,"context_line":"to users. The structure of input and output data should not depend on the"},{"line_number":38,"context_line":"microversion used. Means, specific to the programming language and/or"},{"line_number":39,"context_line":"data formats in use, should be employed to indicate absence or presence of"},{"line_number":40,"context_line":"certain features and behaviors."},{"line_number":41,"context_line":""},{"line_number":42,"context_line":"    For example, a field, missing in the current microversion, can be"},{"line_number":43,"context_line":"    expressed by ``None`` value in Python, ``null`` value in Java or its type"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_474aab27","line":40,"updated":"2018-01-18 18:33:34.000000000","message":"YES!","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":11655,"name":"Julia Kreger","email":"juliaashleykreger@gmail.com","username":"jkreger","status":"Flying to the moon with a Jetpack!"},"change_message_id":"e01b6ccc91b898aa059fe86cf283d3d143405955","unresolved":false,"context_lines":[{"line_number":119,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":120,"context_line":"        # no support for 1.42, falling back to older behavior"},{"line_number":121,"context_line":"        cat.meow()"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"List of versions"},{"line_number":124,"context_line":"~~~~~~~~~~~~~~~~"},{"line_number":125,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_c2dc691a","line":122,"updated":"2018-01-11 17:13:04.000000000","message":"It would still be useful to provide a facility in this case to query the available version range on the server, because the caller might need the ability to write logic that navigates an underlying behavior or process change that is between API versions. If the SDK already has that in memory, depending on operational and architectural constraints, it may be more efficient to choose to call cat.meow() or call an explicitly different version than attempt to handle an exception, especially when one might not be generated.","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0be4d93ba7e08200566dc3c538c3e1d9066ed77d","unresolved":false,"context_lines":[{"line_number":119,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":120,"context_line":"        # no support for 1.42, falling back to older behavior"},{"line_number":121,"context_line":"        cat.meow()"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"List of versions"},{"line_number":124,"context_line":"~~~~~~~~~~~~~~~~"},{"line_number":125,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_690ad58a","line":122,"in_reply_to":"7f96bb07_c2dc691a","updated":"2018-01-15 10:33:02.000000000","message":"Oh, yes","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":11655,"name":"Julia Kreger","email":"juliaashleykreger@gmail.com","username":"jkreger","status":"Flying to the moon with a Jetpack!"},"change_message_id":"e01b6ccc91b898aa059fe86cf283d3d143405955","unresolved":false,"context_lines":[{"line_number":124,"context_line":"~~~~~~~~~~~~~~~~"},{"line_number":125,"context_line":""},{"line_number":126,"context_line":"A modification of `One hardcoded version`_ approach to solve its inherent"},{"line_number":127,"context_line":"problems is to accept a list of versions. The highest available of them will"},{"line_number":128,"context_line":"be negotiated and used for all calls. An SDK implementing this approach must"},{"line_number":129,"context_line":"provide a way for a consumer to learn the negotiated version. The consumer"},{"line_number":130,"context_line":"should use it to modify its behavior accordingly:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_a25efde3","line":127,"range":{"start_line":127,"start_character":72,"end_line":127,"end_character":76},"updated":"2018-01-11 17:13:04.000000000","message":"nit s/will/would/","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0be4d93ba7e08200566dc3c538c3e1d9066ed77d","unresolved":false,"context_lines":[{"line_number":124,"context_line":"~~~~~~~~~~~~~~~~"},{"line_number":125,"context_line":""},{"line_number":126,"context_line":"A modification of `One hardcoded version`_ approach to solve its inherent"},{"line_number":127,"context_line":"problems is to accept a list of versions. The highest available of them will"},{"line_number":128,"context_line":"be negotiated and used for all calls. An SDK implementing this approach must"},{"line_number":129,"context_line":"provide a way for a consumer to learn the negotiated version. The consumer"},{"line_number":130,"context_line":"should use it to modify its behavior accordingly:"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_c96d2933","line":127,"range":{"start_line":127,"start_character":72,"end_line":127,"end_character":76},"in_reply_to":"7f96bb07_a25efde3","updated":"2018-01-15 10:33:02.000000000","message":"Done","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":11655,"name":"Julia Kreger","email":"juliaashleykreger@gmail.com","username":"jkreger","status":"Flying to the moon with a Jetpack!"},"change_message_id":"e01b6ccc91b898aa059fe86cf283d3d143405955","unresolved":false,"context_lines":[{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Another important benefit of this approach is that it allows to specify a"},{"line_number":148,"context_line":"limited number of versions the application was actually tested with. This is a"},{"line_number":149,"context_line":"recommended approach for API that change substantially between microversions."},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"    In our example, the application developer does not have to test the"},{"line_number":152,"context_line":"    application with API versions between 1.0 and 1.42."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_2218ad1b","line":149,"updated":"2018-01-11 17:13:04.000000000","message":"s/API/an API/\ns/change/changes/","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0be4d93ba7e08200566dc3c538c3e1d9066ed77d","unresolved":false,"context_lines":[{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Another important benefit of this approach is that it allows to specify a"},{"line_number":148,"context_line":"limited number of versions the application was actually tested with. This is a"},{"line_number":149,"context_line":"recommended approach for API that change substantially between microversions."},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"    In our example, the application developer does not have to test the"},{"line_number":152,"context_line":"    application with API versions between 1.0 and 1.42."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_e9682522","line":149,"in_reply_to":"7f96bb07_2218ad1b","updated":"2018-01-15 10:33:02.000000000","message":"Done","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":11655,"name":"Julia Kreger","email":"juliaashleykreger@gmail.com","username":"jkreger","status":"Flying to the moon with a Jetpack!"},"change_message_id":"e01b6ccc91b898aa059fe86cf283d3d143405955","unresolved":false,"context_lines":[{"line_number":170,"context_line":"As with `List of versions`_, an SDK implementing this approach must provide"},{"line_number":171,"context_line":"a way for a consumer to learn the negotiated version, and the consumer"},{"line_number":172,"context_line":"should use it to modify its behavior accordingly."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":".. code-block:: python"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"    import catsclient"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_22c3caef","line":173,"updated":"2018-01-11 17:13:04.000000000","message":"I kind of like this approach, although there is still the variation that if I\u0027m requesting a v1 client, I might want the latest response regardless of microversion negotiation. Naturally, such consumers are likely higher level APIs as we\u0027ve learned so far.\n\nAnother plus of this approach is that a project doesn\u0027t necessarily have to block any and all new api microversions from landing before release. Since the client in essence guards, however at the same time, if a project continues to narrow the window to land API features, then that will simply inhibit velocity and frustrate contributors.","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0be4d93ba7e08200566dc3c538c3e1d9066ed77d","unresolved":false,"context_lines":[{"line_number":170,"context_line":"As with `List of versions`_, an SDK implementing this approach must provide"},{"line_number":171,"context_line":"a way for a consumer to learn the negotiated version, and the consumer"},{"line_number":172,"context_line":"should use it to modify its behavior accordingly."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":".. code-block:: python"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"    import catsclient"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_a9e0dd97","line":173,"in_reply_to":"7f96bb07_22c3caef","updated":"2018-01-15 10:33:02.000000000","message":"\u003e I might want the latest response regardless of microversion negotiation\n\nThis has an implicit assumption that response does not change too much in any v1 version. This is not something we guarantee here (from API-SIG standpoint, it may be the case for Ironic).","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":11655,"name":"Julia Kreger","email":"juliaashleykreger@gmail.com","username":"jkreger","status":"Flying to the moon with a Jetpack!"},"change_message_id":"e01b6ccc91b898aa059fe86cf283d3d143405955","unresolved":false,"context_lines":[{"line_number":258,"context_line":"    methods."},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"* `List of versions`_ should be used when API differs a lot from version to"},{"line_number":261,"context_line":"  version to limit the testing scope. This approach is the least flexible."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"* `Latest with lower and upper limit`_ should be used when API development is"},{"line_number":264,"context_line":"  steady and an application may require more flexibility than `List of"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_02632e1c","line":261,"range":{"start_line":261,"start_character":59,"end_line":261,"end_character":74},"updated":"2018-01-11 17:13:04.000000000","message":"It is likely worth noting that it is still more flexible that hard coding a static version for the client to always use.","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0be4d93ba7e08200566dc3c538c3e1d9066ed77d","unresolved":false,"context_lines":[{"line_number":258,"context_line":"    methods."},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"* `List of versions`_ should be used when API differs a lot from version to"},{"line_number":261,"context_line":"  version to limit the testing scope. This approach is the least flexible."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"* `Latest with lower and upper limit`_ should be used when API development is"},{"line_number":264,"context_line":"  steady and an application may require more flexibility than `List of"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7f96bb07_69f4155c","line":261,"range":{"start_line":261,"start_character":59,"end_line":261,"end_character":74},"in_reply_to":"7f96bb07_02632e1c","updated":"2018-01-15 10:33:02.000000000","message":"Yeah, I meant of the recommended approaches. I don\u0027t recommend hard coding a static version.","commit_id":"8bd87985402e9257aada9ed07ac23b873f345620"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"242ae4e64b791fc596b13c71077014e6aa0480dd","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_16fba5c0","line":136,"updated":"2018-01-18 18:33:34.000000000","message":"People get confused already with the difference between API major versions and microversions.\n\nIn keystoneauth the parameter \u0027version\u0027 is for specifying a major version, \u0027min_api_version\u0027 and \u0027max_api_version\u0027 are for specifying a range of acceptable major versions to find from the catalog and \u0027default_microversion\u0027 is for specifying a single microversion at Adapter construction time. Then that combines with Version overwrites below, where each call has a \u0027microversion\u0027 parameter.\n\nWhich is to say I agree with what you are saying, but I\u0027d like to bikeshed on what words we use to talk about each concept.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"55f511cc3b9e8954dce4ba7cbbe54d6e1c2ebe24","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_9f4b05af","line":136,"in_reply_to":"7f96bb07_16fba5c0","updated":"2018-01-22 12:02:00.000000000","message":"I need to say that I hate the word \"microversion\" :) I expect it to be really confusing for people not exposed to the API-SIG work. They will probably expect it to be roughly the same as \"patch version\" in Sem-Ver, which it is not even close to. \n\nIt is not \"micro\" for any definition of \"micro\" I can think of. Including the fact that we can potentially rewrite the whole API with a mere bump of the \"microversion\" :) To add insult to injury, we include the major version in the \"microversion\", so specifying a separate major version is redundant. E.g. in ironicclient:\n\n cli \u003d get_client(1, os_baremetal_api_version\u003d\u00271.42\u0027)\n\nThis is why I\u0027m trying to avoid recommending exposing this notion as it is to innocent consumers.\n\nIn any case, these are just examples. They are not obliging to anything, I hope I made it clear enough somewhere above (lemme know if it was not enough).","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_cbb73af5","line":136,"in_reply_to":"7f96bb07_60e1a3fc","updated":"2018-01-24 16:53:26.000000000","message":"Aren\u0027t we really talking about \u0027major version\u0027 and \u0027minor version\u0027, where microversion \u003d\u003d minor versions of the same major version?\n\nGuess I\u0027m not quite sure where this discussion is going, unless Monty wants some definitions in the beginning of this spec to define the terms so everyone is on the same page?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"9aca7137242f872079b55ab5b0a54a36b8d9782e","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_bfb0418d","line":136,"in_reply_to":"7f96bb07_9f4b05af","updated":"2018-01-22 12:05:07.000000000","message":"By the way, the header is OpenStack-API-Version, not OpenStack-API-Microversion. Nova CLI expects --os-compute-api-version, not --os-compute-api-microversion :) So it does not feel logical to call it microversion here all of a sudden.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"53992d4f8f336bf5c0a5b3b2d245d00e04f771ad","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_40a2679c","line":136,"in_reply_to":"7f96bb07_9f4b05af","updated":"2018-01-22 23:22:02.000000000","message":"I get that the name isn\u0027t ideal, but it *is* well-documented: https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html\n\nWe have all regretted the \"micro\" part of microversions. The historical genesis of the term only makes sense to those who were around when the use of it was begun, and it makes no sense to anyone else. If you like, I can recount it for you over a beer next time we meet. But it is the name that has been set for this system, for better or for worse.\n\nSean Dague is responsible for the name, and he wrote [0]:\n\n\"I\u0027m responsible for two names that took off in OpenStack, one is Microversions. Like any name that catches on you regret it later because it misses the important subtlety of what is going on. Don\u0027t ask me to name things.\"\n\n[0] https://dague.net/2017/12/11/rest-api-microversions/","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"53992d4f8f336bf5c0a5b3b2d245d00e04f771ad","unresolved":false,"context_lines":[{"line_number":133,"context_line":"    import catsclient"},{"line_number":134,"context_line":""},{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_60e1a3fc","line":136,"in_reply_to":"7f96bb07_bfb0418d","updated":"2018-01-22 23:22:02.000000000","message":"If semver had been adopted, I\u0027m sure that the header would still specify \"version\" and not \"semver\". You\u0027re confusing the name of the versioning system with what it manages: a version, in all cases.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"As in this example, an SDK using this approach must provide a clear way to"},{"line_number":141,"context_line":"indicate that the requested version is not supported and do it as early as"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_aa56ca05","line":138,"updated":"2018-01-25 16:28:31.000000000","message":"ack","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":135,"context_line":"    try:"},{"line_number":136,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.42\u0027)"},{"line_number":137,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":138,"context_line":"        sys.exit(\"API microversion 1.42 is not supported\")"},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"As in this example, an SDK using this approach must provide a clear way to"},{"line_number":141,"context_line":"indicate that the requested version is not supported and do it as early as"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_c0c1e030","line":138,"updated":"2018-01-24 16:53:26.000000000","message":"so maybe we should avoid using \u0027microversion\u0027 in the examples? :D","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":162,"context_line":"    try:"},{"line_number":163,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.2\u0027)"},{"line_number":164,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":165,"context_line":"        sys.exit(\"At least API microversion 1.2 is required\")"},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with 1.2"},{"line_number":168,"context_line":"    try:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_2b749e35","line":165,"updated":"2018-01-24 16:53:26.000000000","message":"I\u0027m not sure I understand this example. (and here\u0027s \u0027microversion\u0027 being exposed to the user :))\n\nIf they wanted a client that supports 1.2 and there is this exception, it wouldn\u0027t be true that \u003e\u003d 1.2 is required, cuz if it were true, this exception wouldn\u0027t have happened.\n\nAlso, how do you know that 1.2 is below or above the server\u0027s supported range? (Hopefully the server returned some info that could be put in this exception string...)\n\nSeems like the only thing we could say here is \u0027API version 1.2 is not supported\u0027 ?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":162,"context_line":"    try:"},{"line_number":163,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.2\u0027)"},{"line_number":164,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":165,"context_line":"        sys.exit(\"At least API microversion 1.2 is required\")"},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with 1.2"},{"line_number":168,"context_line":"    try:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_ca5b162c","line":165,"updated":"2018-01-25 16:28:31.000000000","message":"yep, fixing","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":182,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.2\u0027)"},{"line_number":183,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":184,"context_line":"        sys.exit(\"At least API microversion 1.2 is required\")"},{"line_number":185,"context_line":"    min_version, max_version \u003d client.supported_api_versions()"},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with 1.2"},{"line_number":188,"context_line":"    if max_version \u003e\u003d (1, 42):"}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_0e2e9091","line":185,"updated":"2018-01-24 16:53:26.000000000","message":"do we need to be careful here, if two or more major versions are supported? eg this could be (1.45, 2.4) ?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":182,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u00271.2\u0027)"},{"line_number":183,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":184,"context_line":"        sys.exit(\"At least API microversion 1.2 is required\")"},{"line_number":185,"context_line":"    min_version, max_version \u003d client.supported_api_versions()"},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with 1.2"},{"line_number":188,"context_line":"    if max_version \u003e\u003d (1, 42):"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_6a40c236","line":185,"updated":"2018-01-25 16:28:31.000000000","message":"this is something we never truly considered.. Let me try adding something about major versions. note that here we\u0027re using \"v1\" module.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":183,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":184,"context_line":"        sys.exit(\"At least API microversion 1.2 is required\")"},{"line_number":185,"context_line":"    min_version, max_version \u003d client.supported_api_versions()"},{"line_number":186,"context_line":""},{"line_number":187,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with 1.2"},{"line_number":188,"context_line":"    if max_version \u003e\u003d (1, 42):"},{"line_number":189,"context_line":"        cat.bark(api_version\u003d\u00271.42\u0027)  # executed with 1.42"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_a0d93423","line":186,"updated":"2018-01-24 16:53:26.000000000","message":"Ed mentioned this, so maybe important to note (unless it is noted elsewhere), that all minor versions have to be supported between min \u0026 max. Eg, if min\u003d1.3 and max\u003d1.6, 1.3, 1.4, 1.5 and 1.6 must be supported, we can\u0027t just not support 1.5 cuz we don\u0027t like it.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":196,"context_line":""},{"line_number":197,"context_line":"A modification of `One hardcoded version`_ approach to solve its inherent"},{"line_number":198,"context_line":"problems is to accept a list of versions. The highest available of them would"},{"line_number":199,"context_line":"be negotiated and used for all calls. An SDK implementing this approach must"},{"line_number":200,"context_line":"provide a way for a consumer to learn the negotiated version. The consumer"},{"line_number":201,"context_line":"should use it to modify its behavior accordingly:"},{"line_number":202,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_e06bbc1c","line":199,"updated":"2018-01-24 16:53:26.000000000","message":"This looks like a convenience (although useful) thing to me. Cuz I think one could write code that loops through the list of versions, trying to get a client via the hard-coded version approach above. The result of doing that vs the approach being described here, have the same effect at the end of the day. (And if not, maybe someone could highlight what the diff is.)","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":196,"context_line":""},{"line_number":197,"context_line":"A modification of `One hardcoded version`_ approach to solve its inherent"},{"line_number":198,"context_line":"problems is to accept a list of versions. The highest available of them would"},{"line_number":199,"context_line":"be negotiated and used for all calls. An SDK implementing this approach must"},{"line_number":200,"context_line":"provide a way for a consumer to learn the negotiated version. The consumer"},{"line_number":201,"context_line":"should use it to modify its behavior accordingly:"},{"line_number":202,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_8a3d0ebd","line":199,"updated":"2018-01-25 16:28:31.000000000","message":"Yep, it\u0027s the same. I find it valuable to recommend this approach, because it makes the \"Hardcoded version\" approach actually usable.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":226,"context_line":"This approach can also be used with `Version overwrites`_ for flexibility, but"},{"line_number":227,"context_line":"it is somewhat redundant."},{"line_number":228,"context_line":""},{"line_number":229,"context_line":"Negotiated latest"},{"line_number":230,"context_line":"~~~~~~~~~~~~~~~~~"},{"line_number":231,"context_line":""},{"line_number":232,"context_line":"In this approach the SDK is requested to negotiate the highest possible"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_80c2f8e8","line":229,"updated":"2018-01-24 16:53:26.000000000","message":"I was thinking about this term, because we\u0027re exposing that in the ironic client. In my mind, it isn\u0027t a negotiation, it seems fairly straightforward, we determine the max supported version based on the min/max of server, and the max of client. There is only one request to the server to get the min/max.\n\nAnyway, I suspect this falls under bike shedding. I won\u0027t go there though, except to say that I think bike shedding has been given a bad rap. It IS important. Maybe not always.\n\nAnd maybe we should have bike-shedded on \u0027microversion\u0027 :)","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":231,"context_line":""},{"line_number":232,"context_line":"In this approach the SDK is requested to negotiate the highest possible"},{"line_number":233,"context_line":"version with the server. Here \"possible\" means \"the highest version that the"},{"line_number":234,"context_line":"SDK was written to deal with\", unless the authors of the SDK are absolutely"},{"line_number":235,"context_line":"sure that the API will never ever evolve in a way breaking it (which is rarely"},{"line_number":236,"context_line":"a reasonable assumption)."},{"line_number":237,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_2a4aba54","line":234,"updated":"2018-01-25 16:28:31.000000000","message":"Right, it is assumed that we cannot request a version that the server is not supported, as it will reject our request.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":230,"context_line":"~~~~~~~~~~~~~~~~~"},{"line_number":231,"context_line":""},{"line_number":232,"context_line":"In this approach the SDK is requested to negotiate the highest possible"},{"line_number":233,"context_line":"version with the server. Here \"possible\" means \"the highest version that the"},{"line_number":234,"context_line":"SDK was written to deal with\", unless the authors of the SDK are absolutely"},{"line_number":235,"context_line":"sure that the API will never ever evolve in a way breaking it (which is rarely"},{"line_number":236,"context_line":"a reasonable assumption)."},{"line_number":237,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_007348e9","line":234,"range":{"start_line":233,"start_character":48,"end_line":234,"end_character":28},"updated":"2018-01-24 16:53:26.000000000","message":"as well as the maximum version supported by the server, right?\n\nOr maybe I misunderstood the first sentence.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":236,"context_line":"a reasonable assumption)."},{"line_number":237,"context_line":""},{"line_number":238,"context_line":"    For example, if at the time of its 2.5 release an SDK was tested with API"},{"line_number":239,"context_line":"    microversions 1.0 to 1.42, it should not negotiate versions outside of"},{"line_number":240,"context_line":"    this range."},{"line_number":241,"context_line":""},{"line_number":242,"context_line":"As with `List of versions`_, an SDK implementing this approach must provide"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_4a47064d","line":239,"updated":"2018-01-25 16:28:31.000000000","message":"No, the 2nd sentence is right, and I don\u0027t quite see how it contradicts what I said.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":236,"context_line":"a reasonable assumption)."},{"line_number":237,"context_line":""},{"line_number":238,"context_line":"    For example, if at the time of its 2.5 release an SDK was tested with API"},{"line_number":239,"context_line":"    microversions 1.0 to 1.42, it should not negotiate versions outside of"},{"line_number":240,"context_line":"    this range."},{"line_number":241,"context_line":""},{"line_number":242,"context_line":"As with `List of versions`_, an SDK implementing this approach must provide"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_a0061420","line":239,"updated":"2018-01-24 16:53:26.000000000","message":"ok, maybe i misunderstood the first sentence @ L232. I think you mean the SDK will use the maximum version that it supports, in negotiations with the server.\n\nvs what I thought \u0027that the SDK would negotiate with the server, to determine/get the highest possible version supported by both of them\u0027 :)","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":250,"context_line":"    client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027)"},{"line_number":251,"context_line":""},{"line_number":252,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # any version supported by the SDK"},{"line_number":253,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"},{"line_number":254,"context_line":"        cat.bark()  # we know the version to be at least 1.12"},{"line_number":255,"context_line":"    else:"},{"line_number":256,"context_line":"        cat.meow()"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_a3493e61","line":253,"updated":"2018-01-24 16:53:26.000000000","message":"Dmitry, if we want the ironicclient to match this spec, ironicclient has s/negotiated_api_version/current_api_version/","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":250,"context_line":"    client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027)"},{"line_number":251,"context_line":""},{"line_number":252,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # any version supported by the SDK"},{"line_number":253,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"},{"line_number":254,"context_line":"        cat.bark()  # we know the version to be at least 1.12"},{"line_number":255,"context_line":"    else:"},{"line_number":256,"context_line":"        cat.meow()"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_ea75b299","line":253,"updated":"2018-01-25 16:28:31.000000000","message":"actually, here \"current\" feels a bit better","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":280,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027,"},{"line_number":281,"context_line":"                                          min_version\u003d\u00271.2\u0027)"},{"line_number":282,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":283,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with at least 1.2"},{"line_number":286,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_c3bb2a0c","line":283,"updated":"2018-01-24 16:53:26.000000000","message":"I think (hope) you mean something like s/1.2/1.3/ ? Ie, that 1.2 is outside the range that the server supports?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":280,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027,"},{"line_number":281,"context_line":"                                          min_version\u003d\u00271.2\u0027)"},{"line_number":282,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":283,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with at least 1.2"},{"line_number":286,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_0a7b3e8c","line":283,"updated":"2018-01-25 16:28:31.000000000","message":"No, \"latest\" + min_version requires server to support \u003e\u003d 1.2.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":282,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":283,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with at least 1.2"},{"line_number":286,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"},{"line_number":287,"context_line":"        cat.bark()  # executed with at least 1.12"},{"line_number":288,"context_line":"    else:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_23e68eea","line":285,"updated":"2018-01-24 16:53:26.000000000","message":"I guess you aren\u0027t imposing anything here, but really, isn\u0027t this going to use the version that the client @L280 has already decided/negotiated?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":282,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":283,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":284,"context_line":""},{"line_number":285,"context_line":"    cat \u003d client.get_cat(\u0027fluffy\u0027)  # executed with at least 1.2"},{"line_number":286,"context_line":"    if client.negotiated_api_version \u003e\u003d (1, 12):"},{"line_number":287,"context_line":"        cat.bark()  # executed with at least 1.12"},{"line_number":288,"context_line":"    else:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_aa6faac3","line":285,"updated":"2018-01-25 16:28:31.000000000","message":"it is","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":298,"context_line":"    of the ``Cat`` object we use is removed in version 1.43, and the"},{"line_number":299,"context_line":"    application is not written with this change in mind?"},{"line_number":300,"context_line":""},{"line_number":301,"context_line":"In addition to a lower limit, and SDK should also provide an optional upper"},{"line_number":302,"context_line":"limit. Consumers should use it to indicate the maximum version the application"},{"line_number":303,"context_line":"is known to work with, similar to how SDKs itself should have an upper limit."},{"line_number":304,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"7f96bb07_cb5dfa79","line":301,"updated":"2018-01-24 16:53:26.000000000","message":"nit s/and/an/","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":309,"context_line":"    try:"},{"line_number":310,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027,"},{"line_number":311,"context_line":"                                          min_version\u003d\u00271.2\u0027,"},{"line_number":312,"context_line":"                                          max_version\u003d\u00271.42\u0027)"},{"line_number":313,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":314,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":315,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_e3d986f4","line":312,"updated":"2018-01-24 16:53:26.000000000","message":"I don\u0027t understand how this differs from the list one, where you specify api_version\u003d[1.2, 1.42]\n\nErr. Ok, the list one is used to determine the max supported version. What do you think about modifying the list one to be the desired range of versions, including minimum?\n\nAt this point, it feels like there are too many ways, so just wondering if we can refine it.\n\nDoes it make sense to specify \u0027latest\u0027, if max version is specified?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":309,"context_line":"    try:"},{"line_number":310,"context_line":"        client \u003d catsclient.v1.get_client(api_version\u003d\u0027latest\u0027,"},{"line_number":311,"context_line":"                                          min_version\u003d\u00271.2\u0027,"},{"line_number":312,"context_line":"                                          max_version\u003d\u00271.42\u0027)"},{"line_number":313,"context_line":"    except catsclient.IncompatibleApiVersion:"},{"line_number":314,"context_line":"        sys.exit(\"This application requires at least API microversion 1.2\")"},{"line_number":315,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_ca74769c","line":312,"updated":"2018-01-25 16:28:31.000000000","message":"Yep, it does. And to me it does not make sense to NOT specify max_version, because, as I mention somewhere here, it carries an assumption that no future versions will ever break the application.\n\nthe difference between a list of versions and this is quite subtle.","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"86c45708b51edc9654f877171053805452383dfd","unresolved":false,"context_lines":[{"line_number":322,"context_line":"Conclusion"},{"line_number":323,"context_line":"~~~~~~~~~~"},{"line_number":324,"context_line":""},{"line_number":325,"context_line":"This document provides three recommended approaches for low-level SDKs:"},{"line_number":326,"context_line":""},{"line_number":327,"context_line":"* `One hardcoded version`_ with `Version overwrites`_ can be used when maximum"},{"line_number":328,"context_line":"  flexibility is required, and the code is prepared to handle failures due to"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_6a69a2bc","line":325,"updated":"2018-01-25 16:28:31.000000000","message":"Done","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"45a9c60a01c2ec96ffbfa4c64e9b2f7090f1780c","unresolved":false,"context_lines":[{"line_number":322,"context_line":"Conclusion"},{"line_number":323,"context_line":"~~~~~~~~~~"},{"line_number":324,"context_line":""},{"line_number":325,"context_line":"This document provides three recommended approaches for low-level SDKs:"},{"line_number":326,"context_line":""},{"line_number":327,"context_line":"* `One hardcoded version`_ with `Version overwrites`_ can be used when maximum"},{"line_number":328,"context_line":"  flexibility is required, and the code is prepared to handle failures due to"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5f93b717_43ee3a89","line":325,"updated":"2018-01-24 16:53:26.000000000","message":"is the idea to do all three recommendations, or pick exactly one of the tree or ?","commit_id":"59445008bb9e22d577b24c7617e1460542dd3763"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":8,"context_line":"\u003cmicroversion_specification\u003e` in SDKs (software development kits)"},{"line_number":9,"context_line":"targeting OpenStack."},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"This document will consider two kinds of SDKs that may be created for any API."},{"line_number":12,"context_line":"They will differ in the recommended approaches to exposing microversions"},{"line_number":13,"context_line":"to their consumers."},{"line_number":14,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_62cf0256","line":11,"range":{"start_line":11,"start_character":14,"end_line":11,"end_character":27},"updated":"2018-01-31 14:17:41.000000000","message":"considers","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":9,"context_line":"targeting OpenStack."},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"This document will consider two kinds of SDKs that may be created for any API."},{"line_number":12,"context_line":"They will differ in the recommended approaches to exposing microversions"},{"line_number":13,"context_line":"to their consumers."},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"* `High-level SDK`_ is one that hides details of the underlying API from"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_22d57ae5","line":12,"range":{"start_line":12,"start_character":5,"end_line":12,"end_character":9},"updated":"2018-01-31 14:17:41.000000000","message":"\"will\" is not needed","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":15,"context_line":"* `High-level SDK`_ is one that hides details of the underlying API from"},{"line_number":16,"context_line":"  consumers, building its own abstraction layers. Its approach to backward and"},{"line_number":17,"context_line":"  forward compatibility, as well as feature discovery, will be independent of"},{"line_number":18,"context_line":"  the one used by the underlying API. Shade_ is an example of such SDK for"},{"line_number":19,"context_line":"  OpenStack."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* `Low-level SDK`_ is one closely following the structure and design of the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_82fd6e6f","line":18,"range":{"start_line":18,"start_character":67,"end_line":18,"end_character":70},"updated":"2018-01-31 14:17:41.000000000","message":"an SDK ?","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":".. note::"},{"line_number":27,"context_line":"    If in doubt, you should write a high-level SDK. The benefit of using an"},{"line_number":28,"context_line":"    SDK is in consuming API in a way, natural to the programming language and"},{"line_number":29,"context_line":"    any used frameworks. Things like microversions are likely to look foreign"},{"line_number":30,"context_line":"    and confusing for developers who do not specialize on API design."},{"line_number":31,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_42fbe677","line":28,"range":{"start_line":28,"start_character":23,"end_line":28,"end_character":45},"updated":"2018-01-31 14:17:41.000000000","message":"the API in a way that is natural","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":49,"context_line":""},{"line_number":50,"context_line":"    Major versions are distinguished in the URLs by ``/v\u003cNUMBER\u003e`` parts and"},{"line_number":51,"context_line":"    are the first components of a microversion. For example, in microversion"},{"line_number":52,"context_line":"    ``1.42``, ``1`` is a major version."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"    .. note::"},{"line_number":55,"context_line":"        We don\u0027t seem to have an established name for the second component."}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_4229a6e3","line":52,"updated":"2018-01-31 14:17:41.000000000","message":"Not sure how or if to integrate this point in this document, but some APIs (e.g., placement) made a commitment up front to never expose a version identifier in URIs.\n\nIn that context the 1 isn\u0027t really a major version in any traditional sense. It\u0027s just a number.","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"27a2edcc76741a366a08246ed63825e027e297b0","unresolved":false,"context_lines":[{"line_number":140,"context_line":"            cat.meow()"},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"    In this example, ``can_bark`` uses the negotiated microversion to check if"},{"line_number":143,"context_line":"    it is possible for the ``bark`` call to work."},{"line_number":144,"context_line":""},{"line_number":145,"context_line":".. note::"},{"line_number":146,"context_line":"    If possible, an SDK should inform the consumer of the required API"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5f93b717_82b56e80","line":143,"updated":"2018-01-31 14:17:41.000000000","message":"This explanation is a bit facile. How does the client implement can_bark? Do they have an in-code mapping of microversions to available features? Are they expected to have can_* for lots of different features? All of them? A subset? How do they choose?\n\nIf I remember rightly, this is one of the fundamental problems the go-people were having with trying to right a useful SDK: managing all this ambiguity.","commit_id":"a5657420c6232ed6a1b5140e2a467294679757ed"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"c3a6ecfb1964f290fa9f37664d887210066fd5d0","unresolved":false,"context_lines":[{"line_number":47,"context_line":"    but rather a separate generation of the API, co-existing with other"},{"line_number":48,"context_line":"    generations in the same HTTP endpoints tree."},{"line_number":49,"context_line":""},{"line_number":50,"context_line":"    Major versions are distinguished in the URLs by ``/v\u003cNUMBER\u003e`` parts and"},{"line_number":51,"context_line":"    are the first components of a microversion. For example, in microversion"},{"line_number":52,"context_line":"    ``1.42``, ``1`` is a major version."},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"df7087c5_5dc1cfe3","line":50,"range":{"start_line":50,"start_character":4,"end_line":50,"end_character":36},"updated":"2018-03-21 13:04:10.000000000","message":"this only true sometimes","commit_id":"b0903d3b0e02431a258983461859bd91fc94ad6e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"c3a6ecfb1964f290fa9f37664d887210066fd5d0","unresolved":false,"context_lines":[{"line_number":101,"context_line":"    ``None``."},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"An SDK should negotiate the highest microversion that will allow it to serve"},{"line_number":104,"context_line":"consumer\u0027s needs better. However, it should never negotiate a microversion"},{"line_number":105,"context_line":"outside of the range it was written and tested with to avoid confusing"},{"line_number":106,"context_line":"breakages on future changes to the API. It goes without saying that an SDK"},{"line_number":107,"context_line":"should not crush or exhibit undefined behavior on any microversion returned"}],"source_content_type":"text/x-rst","patch_set":7,"id":"df7087c5_bd76ebd7","line":104,"range":{"start_line":104,"start_character":0,"end_line":104,"end_character":10},"updated":"2018-03-21 13:04:10.000000000","message":"consumers","commit_id":"b0903d3b0e02431a258983461859bd91fc94ad6e"},{"author":{"_account_id":841,"name":"Akihiro Motoki","email":"amotoki@gmail.com","username":"amotoki"},"change_message_id":"5c0cbbf7dd7bdb61eea2d4947c17e2e4f9eae323","unresolved":false,"context_lines":[{"line_number":102,"context_line":""},{"line_number":103,"context_line":"An SDK should negotiate the highest microversion that will allow it to serve"},{"line_number":104,"context_line":"consumer\u0027s needs better. However, it should never negotiate a microversion"},{"line_number":105,"context_line":"outside of the range it was written and tested with to avoid confusing"},{"line_number":106,"context_line":"breakages on future changes to the API. It goes without saying that an SDK"},{"line_number":107,"context_line":"should not crush or exhibit undefined behavior on any microversion returned"},{"line_number":108,"context_line":"by a server. Any incompatibilities should be expressed as soon as possible"}],"source_content_type":"text/x-rst","patch_set":7,"id":"bf659307_37b8f628","line":105,"updated":"2018-03-26 04:05:17.000000000","message":"Sometimes it is not easy to test all versions in a specific range.\nIn horizon microvesion support, we pick up specific microversions we know a feature works like nova microvresions corresponding to newton, ocata, pike and queens.\n\n\"a specific set\" might be another candiate instead of \"the range\".\n\nI don\u0027t have a strong opinion on this though.","commit_id":"b0903d3b0e02431a258983461859bd91fc94ad6e"},{"author":{"_account_id":841,"name":"Akihiro Motoki","email":"amotoki@gmail.com","username":"amotoki"},"change_message_id":"5c0cbbf7dd7bdb61eea2d4947c17e2e4f9eae323","unresolved":false,"context_lines":[{"line_number":234,"context_line":"Minimum version"},{"line_number":235,"context_line":"~~~~~~~~~~~~~~~"},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"Applications often have a base minimum API version they are capable of working"},{"line_number":238,"context_line":"with. It is recommended to provide a way to accept such version and use it"},{"line_number":239,"context_line":"as a default when no explicit version is provided:"},{"line_number":240,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"bf659307_57b56a30","line":237,"updated":"2018-03-26 04:05:17.000000000","message":"I think this section discusses a \"default\" version of a client instance.\nI agree such \"default\" version would be \"minimum\" version in most cases.\nWhich is an appropriate term?","commit_id":"b0903d3b0e02431a258983461859bd91fc94ad6e"}]}