)]}'
{"specs/kilo/approved/api-microversions.rst":[{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a9e296c5d70d2a5d8db8861b907e9c4959d44b88","unresolved":false,"context_lines":[{"line_number":23,"context_line":"constantly growing through new extensions, that it\u0027s not likely to be"},{"line_number":24,"context_line":"able to ever do a new major version of the API because of the impact"},{"line_number":25,"context_line":"on users and overhead for developers of supporting multiple"},{"line_number":26,"context_line":"implementations ."},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"At the same time the current situation where we allow innovation in"},{"line_number":29,"context_line":"the API through adding extensions, has grown to the point where we now"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_70083728","line":26,"updated":"2014-10-09 04:25:55.000000000","message":"nit: unnecessary space before \".\"","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"285d631523c800d3644e295b275cdcef25634fb1","unresolved":false,"context_lines":[{"line_number":23,"context_line":"constantly growing through new extensions, that it\u0027s not likely to be"},{"line_number":24,"context_line":"able to ever do a new major version of the API because of the impact"},{"line_number":25,"context_line":"on users and overhead for developers of supporting multiple"},{"line_number":26,"context_line":"implementations ."},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"At the same time the current situation where we allow innovation in"},{"line_number":29,"context_line":"the API through adding extensions, has grown to the point where we now"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_d0cba36f","line":26,"in_reply_to":"baa201ad_70083728","updated":"2014-10-09 04:35:11.000000000","message":"thx!","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a9e296c5d70d2a5d8db8861b907e9c4959d44b88","unresolved":false,"context_lines":[{"line_number":45,"context_line":"A great interface is one that goes out of it\u0027s way to makes it hard to"},{"line_number":46,"context_line":"use incorrectly. A good interface tries to be a great interface, but"},{"line_number":47,"context_line":"bends to the realities of the moment."},{"line_number":48,"context_line":""},{"line_number":49,"context_line":"Use Cases"},{"line_number":50,"context_line":"----------"},{"line_number":51,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_701f575b","line":48,"updated":"2014-10-09 04:25:55.000000000","message":"yeah, I can understand the above. and that seems reasonable and perfect already.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":65,"context_line":"* Deployers of Nova are able to support new features which cause"},{"line_number":66,"context_line":"  backwards incompatible changes to the Nova API without forcing all"},{"line_number":67,"context_line":"  users to modify the way they interact with the API, only those who"},{"line_number":68,"context_line":"  want the new feature."},{"line_number":69,"context_line":""},{"line_number":70,"context_line":"Project Priority"},{"line_number":71,"context_line":"-----------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_b710b8a9","line":68,"updated":"2014-10-10 06:06:20.000000000","message":"What different with line 56?","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":65,"context_line":"* Deployers of Nova are able to support new features which cause"},{"line_number":66,"context_line":"  backwards incompatible changes to the Nova API without forcing all"},{"line_number":67,"context_line":"  users to modify the way they interact with the API, only those who"},{"line_number":68,"context_line":"  want the new feature."},{"line_number":69,"context_line":""},{"line_number":70,"context_line":"Project Priority"},{"line_number":71,"context_line":"-----------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_49d0b250","line":68,"in_reply_to":"9aa7fdbe_be3b4537","updated":"2014-10-21 10:13:32.000000000","message":"I just want to make it clear that there are advantages to both users of the REST API as well as the deployers of Nova. But I\u0027ll merge the two together","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":65,"context_line":"* Deployers of Nova are able to support new features which cause"},{"line_number":66,"context_line":"  backwards incompatible changes to the Nova API without forcing all"},{"line_number":67,"context_line":"  users to modify the way they interact with the API, only those who"},{"line_number":68,"context_line":"  want the new feature."},{"line_number":69,"context_line":""},{"line_number":70,"context_line":"Project Priority"},{"line_number":71,"context_line":"-----------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_be3b4537","line":68,"in_reply_to":"baa201ad_b710b8a9","updated":"2014-10-18 17:02:09.000000000","message":"Yes, I agree with Alex. This is a restatement of the second bullet above.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a9e296c5d70d2a5d8db8861b907e9c4959d44b88","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_f05347df","line":98,"updated":"2014-10-09 04:25:55.000000000","message":"The one of the other options is JSON-Home.\n\nOn JSON-Home REST services can provide API paths(URLs) with each status.\nFor example, if we want to mark some API URLs(like baremetal API, or some proxy APIs), Nova API will provide these API URLs with status \"deprecated\".\n\nor the other example, when we want to change some API URL for consistency, we can add a new URL and mark the old URL as deprecated.\n\nJSON-Home can work together with the other feature because JSON-Home works only if client passes \"application/json-home\". so that does not break existing feature.\nMaybe JSON-Home can complement this feature.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"c7eefd3cacefefd3a35c3a8fb49c08db46a4ba02","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_3c3da88f","line":98,"in_reply_to":"baa201ad_10a7eba7","updated":"2014-10-09 08:06:35.000000000","message":"I agree we should use standards where they already exist, but I think JSON-Home and microversions serve separate purposes.\n\nMicroversions allows us to give control to the client to specify what API they want to talk to. So they can control when new functionality is presented to them or not (that includes backwards compatible changes they may not want to exposed to their app).\n\nWhereas JSON-Home allows us to describe what that API is in a programmatic way. And that may include descriptions involving APIs which are deprecated. There\u0027s AFAIK no mechanism in JSON-Home for a client to request that the API behave in a different manner (say on a specific resource).\n\nSo a sophisticated client may always ask for the latest version of the API and parse the JSON-Home so it knows how to behave in a dynamic fashion. A simple client may just hard code a specific api version request, not try to parse the JSON-HOme document, and just expect the interface to work as the documentation says it should for that version level.\n\nAs much as I want to see JSON-Home in Nova I do think its separate from and lower priority than microversions as JSON-Home doesn\u0027t allow us to make the backwards incompatible changes to the API that we really want such as the tasks API. But I\u0027d welcome a JSON-Home nova spec anytime (I think it probably will need to be generated dynamically because we essentially need one per microversion).","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_a986a063","line":98,"in_reply_to":"baa201ad_3c3da88f","updated":"2014-10-10 06:06:20.000000000","message":"I agree with Chris, JSON-Home and micro-versions are separated purposes. Does Ken\u0027ichi means want to use JSON-HOME to describe micro-version? If yes, that\u0027s option for JSON-HOME, but it still feel not related to micro-version as Chris\u0027s describe.\n\nAnd still think of If we want to generate json-home per micro-version, the json-home still little depend on how to implement micro-version.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"92f429eade855b160f4970ae0548664a5e858a9f","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_10a7eba7","line":98,"in_reply_to":"baa201ad_70b3d709","updated":"2014-10-09 04:44:40.000000000","message":"yeah, I agree that JSON-Home is that it would be complementary to microversions.\n\nThe point of JSON-Home is that JSON-Home is more standard and Keystone has already used it. It would be easy to build a consensus if comparing to all Nova home-made way.\n\nMy idea is that JSON-Home should cover use cases as possible and the remaining things should be covered with Nova home-made microversioning way.\n\nMy priority is\n\n external world standard \u003e OpenStack standard \u003e Nova home-made way","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"97d03f491ac9df168b72fc9fde0a4c12aa2bfecf","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_edecf7f5","line":98,"in_reply_to":"baa201ad_a986a063","updated":"2014-10-22 00:56:18.000000000","message":"@Alex\n\nYeah, that is a very nice point.\nI also imagine/hope JSON-Home will be able to provide API discovery for each micro-version, that would help for clients.\nOne important point is that it should be light-weight implementation because micro-versions will be many and we need to reduce maintenance cost for these implementations.\n\nAnyway, you two are right. JSON-Home should be the separated topic, it is better to concentrate on micro-version without JSON-Home on this spec.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"285d631523c800d3644e295b275cdcef25634fb1","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Versioning"},{"line_number":97,"context_line":"--------------"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"For the purposes of this discussion, \"the API\" is all core and"},{"line_number":100,"context_line":"optional extensions in the Nova tree."},{"line_number":101,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_70b3d709","line":98,"in_reply_to":"baa201ad_f05347df","updated":"2014-10-09 04:35:11.000000000","message":"My view of JSON-Home is that it would be complementary to microversions. You could for example pass the client header when retrieving the json home document and it would describe the api for that specific version. \n\nI don\u0027t think we should be using json home to do another sort of versioning though. Just have one way of doing versioning.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* X when you make incompatible API changes"},{"line_number":107,"context_line":"* Y when you make backwards compatible changes"},{"line_number":108,"context_line":"* Z when you make backwards compatible bug fixes"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":111,"context_line":"under the OpenstAck API Change Guidelines"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_89047cc7","line":108,"updated":"2014-10-10 06:06:20.000000000","message":"This item \"The change is the only way to fix a security bug\" in http://wiki.openstack.org/wiki/APIChangeGuidelines isn\u0027t say it must be backwards compatible fixes.\n\nAnd I think of a case, current release, the lastest api version is 2.11. Previous release\u0027s lastest api version is 2.1. if there is \"security bug bug we want to back port to previous release, in current release, we bump the api version to 2.12. So what we can do for previous release after backport? we call it 2.2 or 2.12?","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":105,"context_line":""},{"line_number":106,"context_line":"* X when you make incompatible API changes"},{"line_number":107,"context_line":"* Y when you make backwards compatible changes"},{"line_number":108,"context_line":"* Z when you make backwards compatible bug fixes"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":111,"context_line":"under the OpenstAck API Change Guidelines"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_a99f5e5e","line":108,"in_reply_to":"baa201ad_89047cc7","updated":"2014-10-21 10:13:32.000000000","message":"So for a backwards incompatible security fix we\u0027d bump the major version number. Eg 2.12.1 would go to 3.0.0. \n\nFor any backports there is simply no good solution. We\u0027d just keep the version number the same and break API compatibility - we don\u0027t want to keep the behavior of that old version anyway because its a security bug.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":108,"context_line":"* Z when you make backwards compatible bug fixes"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":111,"context_line":"under the OpenstAck API Change Guidelines"},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"http://wiki.openstack.org/wiki/APIChangeGuidelines"},{"line_number":114,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_c9aa0485","line":111,"updated":"2014-10-10 06:06:20.000000000","message":"typo, \u0027OpenstAck\u0027","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":110,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":111,"context_line":"under the OpenstAck API Change Guidelines"},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"http://wiki.openstack.org/wiki/APIChangeGuidelines"},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"A version response would look as follows"},{"line_number":116,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_fe45cdb3","line":113,"updated":"2014-10-18 17:02:09.000000000","message":"I disagree with the assertion in the above document that changing a failure HTTP response code to be \"more correct\" is a backwards-compatible change.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":110,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":111,"context_line":"under the OpenstAck API Change Guidelines"},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"http://wiki.openstack.org/wiki/APIChangeGuidelines"},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"A version response would look as follows"},{"line_number":116,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_8979ba31","line":113,"in_reply_to":"9aa7fdbe_fe45cdb3","updated":"2014-10-21 10:13:32.000000000","message":"I think thats a valid viewpoint, but not something we should debate here :-) Let\u0027s leave that discussion to the API WG.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":123,"context_line":"                \"id\": \"v2.0\","},{"line_number":124,"context_line":"                \"links\": ["},{"line_number":125,"context_line":"                      {"},{"line_number":126,"context_line":"                        \"href\": \"http://localhost:8774/v2/\","},{"line_number":127,"context_line":"                        \"rel\": \"self\""},{"line_number":128,"context_line":"                    }"},{"line_number":129,"context_line":"                ],"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_699bd872","line":126,"updated":"2014-10-10 06:06:20.000000000","message":"we will remove \u0027/v2\u0027 from url in the future, Does this require bump api version?","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":123,"context_line":"                \"id\": \"v2.0\","},{"line_number":124,"context_line":"                \"links\": ["},{"line_number":125,"context_line":"                      {"},{"line_number":126,"context_line":"                        \"href\": \"http://localhost:8774/v2/\","},{"line_number":127,"context_line":"                        \"rel\": \"self\""},{"line_number":128,"context_line":"                    }"},{"line_number":129,"context_line":"                ],"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_89a0da91","line":126,"in_reply_to":"baa201ad_699bd872","updated":"2014-10-21 10:13:32.000000000","message":"yes","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":146,"context_line":"A client specifies the version of the API they want via the following"},{"line_number":147,"context_line":"approach, a new header::"},{"line_number":148,"context_line":""},{"line_number":149,"context_line":"  X-OS-Compute-Version: 2.114, experimental, vendor:rax"},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":152,"context_line":"concepts here, global API version, experimental flag, and vendor"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_9e25a10c","line":149,"updated":"2014-10-18 17:02:09.000000000","message":"OS \u003d\u003d Operating System\n\nRecommend being specific, and including the term \"API\" in the header name. How about this?\n\n X-OpenStack-Compute-API-Version","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":146,"context_line":"A client specifies the version of the API they want via the following"},{"line_number":147,"context_line":"approach, a new header::"},{"line_number":148,"context_line":""},{"line_number":149,"context_line":"  X-OS-Compute-Version: 2.114, experimental, vendor:rax"},{"line_number":150,"context_line":""},{"line_number":151,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":152,"context_line":"concepts here, global API version, experimental flag, and vendor"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_29b1aee1","line":149,"in_reply_to":"9aa7fdbe_9e25a10c","updated":"2014-10-21 10:13:32.000000000","message":"I\u0027m fine with that.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":150,"context_line":""},{"line_number":151,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":152,"context_line":"concepts here, global API version, experimental flag, and vendor"},{"line_number":153,"context_line":"flags."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"Semantically this means:"},{"line_number":156,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_fe1cedc3","line":153,"updated":"2014-10-18 17:02:09.000000000","message":"Recommend not having experimental or vendor flags at all. Details below.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":159,"context_line":""},{"line_number":160,"context_line":"* If X-OS-Compute-Version is sent, respond with the API at that"},{"line_number":161,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":162,"context_line":"  return 406 Not Acceptable."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* If X-OS-Compute-Version: latest (special keyword) return max_version"},{"line_number":165,"context_line":"  of the API."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_1e79b1fc","line":162,"updated":"2014-10-18 17:02:09.000000000","message":"++","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":165,"context_line":"  of the API."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"* If experimental is sent, return results with *all* experimental"},{"line_number":168,"context_line":"  extensions enabled."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":171,"context_line":"  of tree vendor extensions."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_de764906","line":168,"updated":"2014-10-18 17:02:09.000000000","message":"-1 for API extensions. If the point of having microversions is to allow our APIs to be evolved over time (including backwards incompatible changes), then we need to get to the point where version X of an API means something consistent. With API extensions, that is not possible... because you would be publishing version X of the API **and all these other thingamabobs in API extensions**, so you\u0027ve now lost all ability of the version X to mean something consistent across multiple deployments of the Nova API.\n\nIMO, we need to make version 2.1.0 be the Nova API without any API extensions, and merge all the existing API extensions in the v2/v3 code into one single API, with version 2.1.0. Only then will we be able to make this blueprint\u0027s objectives a reality.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":165,"context_line":"  of the API."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"* If experimental is sent, return results with *all* experimental"},{"line_number":168,"context_line":"  extensions enabled."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":171,"context_line":"  of tree vendor extensions."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_09186ad2","line":168,"in_reply_to":"9aa7fdbe_de764906","updated":"2014-10-21 10:13:32.000000000","message":"We really really want to be able to set some new features as experimental. A request for experimental features means the client is aware that those bits are subject to change. But we\u0027ve really learnt from experience that often get APIs wrong at first. This allows us to roll something out as experimental, get some decent user testing and not have to commit to supporting something horrible forever. \n\nNote that a request for a non experimental version of the API will be completely stable and consistent across deployments.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":168,"context_line":"  extensions enabled."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":171,"context_line":"  of tree vendor extensions."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":174,"context_line":"installation will return vanilla OpenStack responses at v2. The user"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_3e7e75e5","line":171,"updated":"2014-10-18 17:02:09.000000000","message":"-1 for vendor flag\n\nRecommend getting rid of the vendor: specification entirely. The point of standardizing our APIs is to make them standard, not to allow vendorization. API extensions were an idea designed (in part) to allow vendorization. And we\u0027ve seen how that works out.\n\nLet\u0027s take a hard stand and say \"this is the OpenStack Compute API\" and be done with it. If RAX or HP Cloud or Frobnozzle Cloud wants to have a separate but different API, then they should call it something else, because it\u0027s not the OpenStack Compute API.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":168,"context_line":"  extensions enabled."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":171,"context_line":"  of tree vendor extensions."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":174,"context_line":"installation will return vanilla OpenStack responses at v2. The user"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_0966aa51","line":171,"in_reply_to":"9aa7fdbe_3e7e75e5","updated":"2014-10-21 10:13:32.000000000","message":"So if we want v2.1 deployed in practice then I think we just have to support this. If we don\u0027t standardise how to do it, then various cloud deployers will make up their own which will all be a bit different. \n\nAnd that will make life worse for users. At least this way they know they are dependent on vendor specific features.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":173,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":174,"context_line":"installation will return vanilla OpenStack responses at v2. The user"},{"line_number":175,"context_line":"or SDK will have to ask for something different in order to get new"},{"line_number":176,"context_line":"features."},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_09a24c9a","line":176,"updated":"2014-10-10 06:06:20.000000000","message":"The pyhon-novaclient always support the lastest version? And also we should describe what strategy, like whether python-novaclient support multiple version, or just lastest version.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2b1a029a84081a178c9c228e3c5d141ea7e9c678","unresolved":false,"context_lines":[{"line_number":173,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":174,"context_line":"installation will return vanilla OpenStack responses at v2. The user"},{"line_number":175,"context_line":"or SDK will have to ask for something different in order to get new"},{"line_number":176,"context_line":"features."},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_ff8776b4","line":176,"in_reply_to":"baa201ad_09a24c9a","updated":"2014-10-10 08:20:19.000000000","message":"IMO, pyhon-novaclient should support all supported version as API if we want to make it behave like practical/real client otherwise as microversion grow it will become more like unusable for many users.\n\nThat might not fit easily in their current design.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"3a2869a1e3f02e88ef425ed6ad795c4cafc8da2a","unresolved":false,"context_lines":[{"line_number":173,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":174,"context_line":"installation will return vanilla OpenStack responses at v2. The user"},{"line_number":175,"context_line":"or SDK will have to ask for something different in order to get new"},{"line_number":176,"context_line":"features."},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_825d31ef","line":176,"in_reply_to":"baa201ad_ff8776b4","updated":"2014-10-10 08:32:48.000000000","message":"I\u0027m think of can we make python-novaclient to be the json-home consumer. That will be huge change.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":175,"context_line":"or SDK will have to ask for something different in order to get new"},{"line_number":176,"context_line":"features."},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":180,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":181,"context_line":"these things back in tree."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_1e60d134","line":178,"updated":"2014-10-18 17:02:09.000000000","message":"s/by being virtue of/by virtue of being/","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":180,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":181,"context_line":"these things back in tree."},{"line_number":182,"context_line":""},{"line_number":183,"context_line":"Here is where you cover the change you propose to make in detail. How do you"},{"line_number":184,"context_line":"propose to solve this problem?"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_5e5a5984","line":181,"updated":"2014-10-18 17:02:09.000000000","message":"Agree with the sentiment. But, I think we need to get rid of API extensions and vendorization with the release of the 2.1.0 Nova API.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":178,"context_line":"Experimental and vendor, by being virtue of out of tree, do not"},{"line_number":179,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":180,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":181,"context_line":"these things back in tree."},{"line_number":182,"context_line":""},{"line_number":183,"context_line":"Here is where you cover the change you propose to make in detail. How do you"},{"line_number":184,"context_line":"propose to solve this problem?"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_e9bc066f","line":181,"in_reply_to":"9aa7fdbe_5e5a5984","updated":"2014-10-21 10:13:32.000000000","message":"I think its simply too soon to do this in v2.1. We need microversions early in the kilo cycle if we are going to get important features like the tasks API in.\n\nThe debate over what extensions are in and what are out is going to be the never ending thread of doom. And I don\u0027t think we can wait for it.\n\nAlso, remember that v2.1 needs to work exactly the same as the v2 api. Which means we need to support everything. Otherwise we can\u0027t delete the old v2 api code and we really want to do that asap.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":184,"context_line":"propose to solve this problem?"},{"line_number":185,"context_line":""},{"line_number":186,"context_line":"If this is one part of a larger effort make it clear where this piece ends. In"},{"line_number":187,"context_line":"other words, what\u0027s the scope of this effort?"},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Implementation design details"},{"line_number":190,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_9e53e16b","line":187,"updated":"2014-10-18 17:02:09.000000000","message":"Remove above two paragraphs :) Copy/pasted from template...","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":184,"context_line":"propose to solve this problem?"},{"line_number":185,"context_line":""},{"line_number":186,"context_line":"If this is one part of a larger effort make it clear where this piece ends. In"},{"line_number":187,"context_line":"other words, what\u0027s the scope of this effort?"},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Implementation design details"},{"line_number":190,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_09c22ae9","line":187,"in_reply_to":"9aa7fdbe_9e53e16b","updated":"2014-10-21 10:13:32.000000000","message":"thx, done","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"b4b97648db6d622c2f9252494abff2506acafb18","unresolved":false,"context_lines":[{"line_number":189,"context_line":"Implementation design details"},{"line_number":190,"context_line":"-----------------------------"},{"line_number":191,"context_line":""},{"line_number":192,"context_line":"On each request the X-OS-Computer-Version header string will be"},{"line_number":193,"context_line":"converted to an APIVersionRequest object in the wsgi code. Routing"},{"line_number":194,"context_line":"will occur in the usual manner with the version object attached to the"},{"line_number":195,"context_line":"request object (which all API methods expect). The API methods can"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_f777a039","line":192,"updated":"2014-10-10 04:38:37.000000000","message":"X-OS-Compute*r* version.  I guess this is a typo ;P","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":197,"context_line":""},{"line_number":198,"context_line":"What other ways could we do this thing? Why aren\u0027t we using those? This doesn\u0027t"},{"line_number":199,"context_line":"have to be a full literature review, but it should demonstrate that thought has"},{"line_number":200,"context_line":"been put into why the proposed solution is an appropriate one."},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"Types of changes we will need to support::"},{"line_number":203,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_be50a55f","line":200,"updated":"2014-10-18 17:02:09.000000000","message":"Remove the above paragraph... copy/pasted from template (and belongs in the Alternatives section I think.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":197,"context_line":""},{"line_number":198,"context_line":"What other ways could we do this thing? Why aren\u0027t we using those? This doesn\u0027t"},{"line_number":199,"context_line":"have to be a full literature review, but it should demonstrate that thought has"},{"line_number":200,"context_line":"been put into why the proposed solution is an appropriate one."},{"line_number":201,"context_line":""},{"line_number":202,"context_line":"Types of changes we will need to support::"},{"line_number":203,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_a9aafe16","line":200,"in_reply_to":"9aa7fdbe_be50a55f","updated":"2014-10-21 10:13:32.000000000","message":"Done","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":201,"context_line":""},{"line_number":202,"context_line":"Types of changes we will need to support::"},{"line_number":203,"context_line":""},{"line_number":204,"context_line":"* Status code changes (success and error codes)"},{"line_number":205,"context_line":"* Allowable body parameters (affects input validation schemas too)"},{"line_number":206,"context_line":"* Allowable url parameters"},{"line_number":207,"context_line":"* General semantic changes"}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_491ff4b7","line":204,"updated":"2014-10-10 06:06:20.000000000","message":"Emm...if we change error code, then bump the version, and we choice keep all the back-compatible version, that will be a little pain. I didn\u0027t think about this case before.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":204,"context_line":"* Status code changes (success and error codes)"},{"line_number":205,"context_line":"* Allowable body parameters (affects input validation schemas too)"},{"line_number":206,"context_line":"* Allowable url parameters"},{"line_number":207,"context_line":"* General semantic changes"},{"line_number":208,"context_line":"* Data returned in response"},{"line_number":209,"context_line":"* ???"},{"line_number":210,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_de4d69c6","line":207,"updated":"2014-10-18 17:02:09.000000000","message":"Like tasks...","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":206,"context_line":"* Allowable url parameters"},{"line_number":207,"context_line":"* General semantic changes"},{"line_number":208,"context_line":"* Data returned in response"},{"line_number":209,"context_line":"* ???"},{"line_number":210,"context_line":""},{"line_number":211,"context_line":"THIS SECTION IS NOT COMPLETE"},{"line_number":212,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_fe4a2dab","line":209,"updated":"2014-10-18 17:02:09.000000000","message":"I would also include:\n\n* Removal of resources in the API\n* Removal of fields in a response object\n* Removal of top-level dictionary key that is the same as the resource name (for instance the top-level \"server\" key in the response from GET /servers/\u003cUUID\u003e is not necessary at all. Are we stuck with this? How can we get rid of this in future API versions?","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":206,"context_line":"* Allowable url parameters"},{"line_number":207,"context_line":"* General semantic changes"},{"line_number":208,"context_line":"* Data returned in response"},{"line_number":209,"context_line":"* ???"},{"line_number":210,"context_line":""},{"line_number":211,"context_line":"THIS SECTION IS NOT COMPLETE"},{"line_number":212,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_09378a00","line":209,"in_reply_to":"9aa7fdbe_fe4a2dab","updated":"2014-10-21 10:13:32.000000000","message":"Since we really should be returning multiple server responses for the multiple create case the top level server key might stay. It has to stay for v2.1 of course, but we\u0027ll see what happens with tasks (its out of scope for this spec anyway but I agree that its the type of thing we can change)","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"878cba5cc8c0c195ff5853fddd38395b43c58d3b","unresolved":false,"context_lines":[{"line_number":273,"context_line":"FAQ"},{"line_number":274,"context_line":"---"},{"line_number":275,"context_line":""},{"line_number":276,"context_line":"* Does adding a new plugin change the version number?"},{"line_number":277,"context_line":"  Yes. Although a client could detect this also through /extensions"},{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_1ec7f113","line":276,"updated":"2014-10-18 17:02:09.000000000","message":"What do you mean by \"plugin\"? If you are referring to API extensions, see my above plea to get rid of them entirely.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"f88ea9a61fc9db8a799c3b77f6e5555fdb936bca","unresolved":false,"context_lines":[{"line_number":273,"context_line":"FAQ"},{"line_number":274,"context_line":"---"},{"line_number":275,"context_line":""},{"line_number":276,"context_line":"* Does adding a new plugin change the version number?"},{"line_number":277,"context_line":"  Yes. Although a client could detect this also through /extensions"},{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_dc9b7ec7","line":276,"in_reply_to":"9aa7fdbe_1ec7f113","updated":"2014-10-21 10:13:32.000000000","message":"So from an implementation point of view everything in the API is a stevedore plugin. At the moment there is a 1:1 mapping of plugins to \"extensions\". But to \"get rid\" of extensions we can simply make all plugins compulsory.\n\nBut what I\u0027m getting to here is a plugin may add a new resource or extend a current one and the client needs to know it is available. JSON-Home would obviously provide this, but for those who don\u0027t want to do the discovery dance, I think we should also bump the minor version number. ie. they can just request a specific version of the API and they know they will get the feature they are after.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2b1a029a84081a178c9c228e3c5d141ea7e9c678","unresolved":false,"context_lines":[{"line_number":276,"context_line":"* Does adding a new plugin change the version number?"},{"line_number":277,"context_line":"  Yes. Although a client could detect this also through /extensions"},{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."},{"line_number":280,"context_line":""},{"line_number":281,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":282,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_df3f12d5","line":279,"updated":"2014-10-10 08:20:19.000000000","message":"Yes that\u0027s the nice way to market new plugin.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"dc84d5af00a7bafcf6b4ceb8b56eb0953afc1d40","unresolved":false,"context_lines":[{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."},{"line_number":280,"context_line":""},{"line_number":281,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":282,"context_line":""},{"line_number":283,"context_line":""},{"line_number":284,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_49761408","line":281,"updated":"2014-10-10 06:06:20.000000000","message":"Emm...same concern at line 204","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2b1a029a84081a178c9c228e3c5d141ea7e9c678","unresolved":false,"context_lines":[{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."},{"line_number":280,"context_line":""},{"line_number":281,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":282,"context_line":""},{"line_number":283,"context_line":""},{"line_number":284,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_ff75b6cc","line":281,"in_reply_to":"baa201ad_49761408","updated":"2014-10-10 08:20:19.000000000","message":"I also agree with that. it should be without version bump","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"e1a69102ecdd5590906de24dffb244fae63a65bf","unresolved":false,"context_lines":[{"line_number":278,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":279,"context_line":"  it could be present."},{"line_number":280,"context_line":""},{"line_number":281,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":282,"context_line":""},{"line_number":283,"context_line":""},{"line_number":284,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"baa201ad_0dccfb34","line":281,"in_reply_to":"baa201ad_ff75b6cc","updated":"2014-10-11 03:38:55.000000000","message":"change the error status code should be bug fix for the api. So it only bump the Z version, and we can just keep the lastest Z version for the api.","commit_id":"0f42e0acd76108c1d5e58cbff52698a15aa9e461"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf0665d49a2b5ef6eb62356f2c71938640b9c213","unresolved":false,"context_lines":[{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* X when you make incompatible API changes"},{"line_number":104,"context_line":"* Y when you make backwards compatible changes"},{"line_number":105,"context_line":"* Z when you make backwards compatible bug fixes"},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":108,"context_line":"under the OpenStack API Change Guidelines"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_4d3c23e3","line":105,"updated":"2014-10-22 01:06:17.000000000","message":"As Alex and Chris discussion, Z seems to cause confusions. Can we remove Z because it would be easy to increment X/Y value from compatible/incompatible point of view.","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* X when you make incompatible API changes"},{"line_number":104,"context_line":"* Y when you make backwards compatible changes"},{"line_number":105,"context_line":"* Z when you make backwards compatible bug fixes"},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":108,"context_line":"under the OpenStack API Change Guidelines"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_46d5a2b7","line":105,"in_reply_to":"9aa7fdbe_4d3c23e3","updated":"2014-10-23 23:53:11.000000000","message":"Yea I\u0027m ok with that. The difference between a bug fix and a backwards compatible change can be pretty small anyway","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf0665d49a2b5ef6eb62356f2c71938640b9c213","unresolved":false,"context_lines":[{"line_number":126,"context_line":"                ],"},{"line_number":127,"context_line":"                \"status\": \"CURRENT\","},{"line_number":128,"context_line":"                \"version\": \"5.2.0\""},{"line_number":129,"context_line":"                \"min_version\": \"2.0\""},{"line_number":130,"context_line":"            },"},{"line_number":131,"context_line":"       ]"},{"line_number":132,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_2d67df26","line":129,"updated":"2014-10-22 01:06:17.000000000","message":"min_version will be \"2.1\" because this is based on v2.1 API.","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":126,"context_line":"                ],"},{"line_number":127,"context_line":"                \"status\": \"CURRENT\","},{"line_number":128,"context_line":"                \"version\": \"5.2.0\""},{"line_number":129,"context_line":"                \"min_version\": \"2.0\""},{"line_number":130,"context_line":"            },"},{"line_number":131,"context_line":"       ]"},{"line_number":132,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_7a24f6ae","line":129,"in_reply_to":"9aa7fdbe_2d67df26","updated":"2014-10-23 23:53:11.000000000","message":"Done","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf0665d49a2b5ef6eb62356f2c71938640b9c213","unresolved":false,"context_lines":[{"line_number":151,"context_line":""},{"line_number":152,"context_line":"Semantically this means:"},{"line_number":153,"context_line":""},{"line_number":154,"context_line":"* If X-OS-Compute-Version is not provided, act as if min_version was"},{"line_number":155,"context_line":"  sent."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* If X-OS-Compute-Version is sent, respond with the API at that"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_6d5e4778","line":154,"updated":"2014-10-22 01:06:17.000000000","message":"s/X-OS-Compute-Version/X-OpenStack-Compute-API-Version/","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":151,"context_line":""},{"line_number":152,"context_line":"Semantically this means:"},{"line_number":153,"context_line":""},{"line_number":154,"context_line":"* If X-OS-Compute-Version is not provided, act as if min_version was"},{"line_number":155,"context_line":"  sent."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* If X-OS-Compute-Version is sent, respond with the API at that"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_9a3c3aca","line":154,"in_reply_to":"9aa7fdbe_6d5e4778","updated":"2014-10-23 23:53:11.000000000","message":"Done","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf0665d49a2b5ef6eb62356f2c71938640b9c213","unresolved":false,"context_lines":[{"line_number":154,"context_line":"* If X-OS-Compute-Version is not provided, act as if min_version was"},{"line_number":155,"context_line":"  sent."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* If X-OS-Compute-Version is sent, respond with the API at that"},{"line_number":158,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":159,"context_line":"  return 406 Not Acceptable."},{"line_number":160,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_cd4e53c1","line":157,"updated":"2014-10-22 01:06:17.000000000","message":"ditto","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":154,"context_line":"* If X-OS-Compute-Version is not provided, act as if min_version was"},{"line_number":155,"context_line":"  sent."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* If X-OS-Compute-Version is sent, respond with the API at that"},{"line_number":158,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":159,"context_line":"  return 406 Not Acceptable."},{"line_number":160,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_ba39fed8","line":157,"in_reply_to":"9aa7fdbe_cd4e53c1","updated":"2014-10-23 23:53:11.000000000","message":"Done","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"cf0665d49a2b5ef6eb62356f2c71938640b9c213","unresolved":false,"context_lines":[{"line_number":158,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":159,"context_line":"  return 406 Not Acceptable."},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"* If X-OS-Compute-Version: latest (special keyword) return max_version"},{"line_number":162,"context_line":"  of the API."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* If experimental is sent, return results with *all* experimental"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_0dc85b21","line":161,"updated":"2014-10-22 01:06:17.000000000","message":"ditto","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":158,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":159,"context_line":"  return 406 Not Acceptable."},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"* If X-OS-Compute-Version: latest (special keyword) return max_version"},{"line_number":162,"context_line":"  of the API."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* If experimental is sent, return results with *all* experimental"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_da3242f1","line":161,"in_reply_to":"9aa7fdbe_0dc85b21","updated":"2014-10-23 23:53:11.000000000","message":"Done","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"2eaa4fcc1754a174c50f1d34093ec4455f9cb721","unresolved":false,"context_lines":[{"line_number":203,"context_line":""},{"line_number":204,"context_line":"::"},{"line_number":205,"context_line":""},{"line_number":206,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1.0\u0027, max_version\u003d\u00272.9.0\u0027\u0027)"},{"line_number":207,"context_line":"\u003e  def show(self, req, id):"},{"line_number":208,"context_line":"\u003e       pass"},{"line_number":209,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_485971fd","line":206,"updated":"2014-10-22 01:26:45.000000000","message":"Additional \u0027 char:\n@api_version(min_version\u003d\u00272.1.0\u0027, max_version\u003d\u00272.9.0\u0027)","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"2eaa4fcc1754a174c50f1d34093ec4455f9cb721","unresolved":false,"context_lines":[{"line_number":227,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1.0\u0027)"},{"line_number":228,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":229,"context_line":"\u003e      pass"},{"line_number":230,"context_line":"\u003e"},{"line_number":231,"context_line":"\u003e   def show(self, req, id):"},{"line_number":232,"context_line":"\u003e      .... common stuff ...."},{"line_number":233,"context_line":"\u003e      self._version_specific_func(req, \"foo\")"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_c8900198","line":230,"updated":"2014-10-22 01:26:45.000000000","message":"I /think/ I understand what you\u0027re going for here but if I do the example code would be more like:\n\n---\n@api_version(min_version\u003d\u00272.1.0\u0027, max_version\u003d\u00272.9.0\u0027)\ndef _version_specific_func(self, req, arg1):\n    pass\n\n@api_version(min_version\u003d\u00273.0.0\u0027)\ndef _version_specific_func(self, req, arg1):\n    pass\n---\n\nWouldn\u0027t it?","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":227,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1.0\u0027)"},{"line_number":228,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":229,"context_line":"\u003e      pass"},{"line_number":230,"context_line":"\u003e"},{"line_number":231,"context_line":"\u003e   def show(self, req, id):"},{"line_number":232,"context_line":"\u003e      .... common stuff ...."},{"line_number":233,"context_line":"\u003e      self._version_specific_func(req, \"foo\")"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_9a435a41","line":230,"in_reply_to":"9aa7fdbe_c8900198","updated":"2014-10-23 23:53:11.000000000","message":"ah yes, thanks!","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"2eaa4fcc1754a174c50f1d34093ec4455f9cb721","unresolved":false,"context_lines":[{"line_number":257,"context_line":"@api_vendor(\"vendor_string\")"},{"line_number":258,"context_line":""},{"line_number":259,"context_line":"Note that you cannot combine these with the api_version decorator or"},{"line_number":260,"context_line":"with each other."},{"line_number":261,"context_line":""},{"line_number":262,"context_line":"Some prototype code which explains how this work is available here:"},{"line_number":263,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_e8fea5ad","line":260,"updated":"2014-10-22 01:26:45.000000000","message":"So there is no such thing as an \u0027experimental\u0027 vendor extension?","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":257,"context_line":"@api_vendor(\"vendor_string\")"},{"line_number":258,"context_line":""},{"line_number":259,"context_line":"Note that you cannot combine these with the api_version decorator or"},{"line_number":260,"context_line":"with each other."},{"line_number":261,"context_line":""},{"line_number":262,"context_line":"Some prototype code which explains how this work is available here:"},{"line_number":263,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_ba401e35","line":260,"in_reply_to":"9aa7fdbe_e8fea5ad","updated":"2014-10-23 23:53:11.000000000","message":"No, I don\u0027t think we need to support it. Could be convinced otherwise, but vendors could start using exp, and then promote it to vendor for release.","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"2eaa4fcc1754a174c50f1d34093ec4455f9cb721","unresolved":false,"context_lines":[{"line_number":302,"context_line":"Other end user impact"},{"line_number":303,"context_line":"---------------------"},{"line_number":304,"context_line":""},{"line_number":305,"context_line":"SDK authors will need to start using the X-OS-Compute-Version header"},{"line_number":306,"context_line":"to get access to new features. The fact that new features will only be"},{"line_number":307,"context_line":"added in new versions will encourage them to do so."},{"line_number":308,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_08d4c91e","line":305,"updated":"2014-10-22 01:26:45.000000000","message":"X-Openstack-Compute-Version","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"afab31e60f6ca558f6a0e526eb7a61fc2b410a81","unresolved":false,"context_lines":[{"line_number":302,"context_line":"Other end user impact"},{"line_number":303,"context_line":"---------------------"},{"line_number":304,"context_line":""},{"line_number":305,"context_line":"SDK authors will need to start using the X-OS-Compute-Version header"},{"line_number":306,"context_line":"to get access to new features. The fact that new features will only be"},{"line_number":307,"context_line":"added in new versions will encourage them to do so."},{"line_number":308,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9aa7fdbe_fa46264e","line":305,"in_reply_to":"9aa7fdbe_08d4c91e","updated":"2014-10-23 23:53:11.000000000","message":"Done","commit_id":"1c046f2c7d23a34559e518ff4e9203a4355415f9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"844cbbcf5292758d648a25d96969fdc57a31d015","unresolved":false,"context_lines":[{"line_number":142,"context_line":"A client specifies the version of the API they want via the following"},{"line_number":143,"context_line":"approach, a new header::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"  X-OpenStack-Compute-API-Version: 2.114, experimental, vendor:rax"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":148,"context_line":"concepts here, global API version, experimental flag, and vendor"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_cc4fc332","line":145,"updated":"2014-10-27 12:12:30.000000000","message":"Should client specify backwards compatible change version(version Y)?\nHow about that client cannot specify backwards compatible change version ?\n\n eg:\n   X-OpenStack-Compute-API-Version: 3, experimental, vendor:rax\n\nOn the current API(v2.0), deployers only can select API extensions which are backwards compatible changes. For example, extended_server_attributes extension adds \"OS-EXT-SRV-ATTR:hypervisor_hostname\" attribute into a response body and that would be backwards compatible change. Now client cannot disable/enable this extension, deployers only can do it.\n\nHowever, the above description seems to allow this right to client.\nThis would be maintenance cost, because Nova should provide each backwards compatible change.\n\nSo I\u0027d like to suggest client can specify version X(backwards incompatible changes) only for maintenance cost and simple interface.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"0d9e872e2a9d7795da51d3f6bac6772b3e945a30","unresolved":false,"context_lines":[{"line_number":142,"context_line":"A client specifies the version of the API they want via the following"},{"line_number":143,"context_line":"approach, a new header::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"  X-OpenStack-Compute-API-Version: 2.114, experimental, vendor:rax"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":148,"context_line":"concepts here, global API version, experimental flag, and vendor"}],"source_content_type":"text/x-rst","patch_set":7,"id":"7a8c0949_f5f087cb","line":145,"in_reply_to":"9aa7fdbe_6d523536","updated":"2014-10-30 07:38:10.000000000","message":"@Chris\n\n \u003e However, it brings up an interesting point. If they request say 3.1 can we actually\n \u003e serve 3.2 as it is backwards compatible? That may save us testing bandwidth.\n\nYeah, that is what I wanted to point.\nand we can save us implementation cost also.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"b3e5a63dbabb12e622262ea5a92751ff96d57c71","unresolved":false,"context_lines":[{"line_number":142,"context_line":"A client specifies the version of the API they want via the following"},{"line_number":143,"context_line":"approach, a new header::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"  X-OpenStack-Compute-API-Version: 2.114, experimental, vendor:rax"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"This conceptually acts like the accept header.  We introduce 3"},{"line_number":148,"context_line":"concepts here, global API version, experimental flag, and vendor"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_6d523536","line":145,"in_reply_to":"9aa7fdbe_cc4fc332","updated":"2014-10-29 10:29:14.000000000","message":"So if we say have versions 3.0, 3.1, 3.2, the clients need to be able to be able to specify that they want version 3.2, because version 3.1 may not have the features they want. And they don\u0027t want to have to do the jsonschema/json-home parsing to see if their feature is present. If they can only request version 3, then they don\u0027t know what they are going to get as the server may not support version 3.2. If they specify what version they want we can reject a request with a 406 if we don\u0027t support it.\n\nHowever, it brings up an interesting point. If they request say 3.1 can we actually serve 3.2 as it is backwards compatible? That may save us testing bandwidth. I think the only reason that a client may want an exact version match is they are using a non dynamic language and can\u0027t easily handle extra parameters.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":151,"context_line":"Semantically this means:"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"* If X-OpenStack-Compute-API-Version is not provided, act as if min_version was"},{"line_number":154,"context_line":"  sent."},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_9307aec9","line":154,"updated":"2014-10-24 19:44:05.000000000","message":"So. This is kinda reasonable, because the client should have checked /versions first to see if it likes the minimum version. However, for naive and older clients, this might not be enough. I feel like maybe we should make the absence of this header mean (forever) v2.1, and if we stop supporting 2.1, then take whatever behavior we\u0027re going to do if they request an unsupported version.\n\nBut, I guess I\u0027m a little on the fence. Does anyone feel strongly that we should have the behavior described in the spec here?\n\nI kinda feel like if we allow it to be skipped and still get expected behavior, we\u0027ll have clients that don\u0027t change, and if/when we start to raise the minimum version, they\u0027ll start breaking in small but varied ways. Shouldn\u0027t we take the more concrete path here?","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":151,"context_line":"Semantically this means:"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"* If X-OpenStack-Compute-API-Version is not provided, act as if min_version was"},{"line_number":154,"context_line":"  sent."},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_175abc82","line":154,"in_reply_to":"9aa7fdbe_9307aec9","updated":"2014-10-26 23:31:22.000000000","message":"I think the stricter behaviour you propose is better. It will cause us and users less problems in the long term.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":158,"context_line":"  return 406 Not Acceptable."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"* If X-OpenStack-Compute-API-Version: latest (special keyword) return"},{"line_number":161,"context_line":"  max_version of the API."}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_331fe209","line":158,"updated":"2014-10-24 19:44:05.000000000","message":"I don\u0027t think this is enough. I think we should return 406, with a Mime-Type of audio/mpeg3, and this as the content: https://www.youtube.com/watch?v\u003dHP8sofAN4xc.\n\n\n\n\n\n\n(no not really)","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":158,"context_line":"  return 406 Not Acceptable."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"* If X-OpenStack-Compute-API-Version: latest (special keyword) return"},{"line_number":161,"context_line":"  max_version of the API."}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_375d007a","line":158,"in_reply_to":"9aa7fdbe_331fe209","updated":"2014-10-26 23:31:22.000000000","message":"hah :)","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":174,"context_line":"Experimental and vendor, by virtue of being out of tree, do not"},{"line_number":175,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":176,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":177,"context_line":"these things back in tree."},{"line_number":178,"context_line":""},{"line_number":179,"context_line":"Implementation design details"},{"line_number":180,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_53ef06e9","line":177,"updated":"2014-10-24 19:44:05.000000000","message":"Presumably we return the same 406 if they send some other keyword we don\u0027t recognize or the header is otherwise malformed?","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":174,"context_line":"Experimental and vendor, by virtue of being out of tree, do not"},{"line_number":175,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":176,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":177,"context_line":"these things back in tree."},{"line_number":178,"context_line":""},{"line_number":179,"context_line":"Implementation design details"},{"line_number":180,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_77522868","line":177,"in_reply_to":"9aa7fdbe_53ef06e9","updated":"2014-10-26 23:31:22.000000000","message":"So I think if the header is totally unparseable will probably return 400. If its just got invalid keywords then 406 is fine. I however don\u0027t propose that we keep a list of valid vendor strings. It will match the vendor strings if possible, but if there\u0027s a typo, bad luck.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"1714484865e0770fde73c53dfc42c17043238092","unresolved":false,"context_lines":[{"line_number":174,"context_line":"Experimental and vendor, by virtue of being out of tree, do not"},{"line_number":175,"context_line":"benefit from versioning. It\u0027s an all or nothing affair. There are less"},{"line_number":176,"context_line":"unique snowflakes in the world than people think, and we actually want"},{"line_number":177,"context_line":"these things back in tree."},{"line_number":178,"context_line":""},{"line_number":179,"context_line":"Implementation design details"},{"line_number":180,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_fa75e7f9","line":177,"in_reply_to":"9aa7fdbe_77522868","updated":"2014-10-28 18:22:00.000000000","message":"Yep, agreed about the vendor flags for sure.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"2cdc93fb4c13727b7b7847648502fb3c8a65ac75","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_50f2b306","line":205,"updated":"2014-10-24 05:52:32.000000000","message":"Big +1 for this,\n\nI have same propose: https://github.com/soulxu/nova-v3-api-doc/commit/704118c9e69891dd32729903b348bf85ab136a72\n\nFor any back-compatibile changes(only bump the minor version), we can share some code.\n\nBut I think for any response/reqeust back-incompatible changes, it needn\u0027t writing another version function also. But that\u0027s depend on how can we hide the changes for  request/response in python code(see the comment at line 268).","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_d7caf419","line":205,"in_reply_to":"9aa7fdbe_50f2b306","updated":"2014-10-26 23:31:22.000000000","message":"Alex - so I don\u0027t think this is fundamentally is really any different from translating which got rejected earlier. Instead of translating to the latest format, we\u0027d be translating to a common dict format. Also (and this is for both cases) we\u0027d still need to have some version specific handling in the code itself (eg an extra parameter still needs some extra handling).\n\nNow personally I\u0027m for doing some translation work for input/output as I think its simpler, but that approach basically got rejected last time around.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_d30a1678","line":205,"in_reply_to":"9aa7fdbe_50f2b306","updated":"2014-10-24 19:44:05.000000000","message":"What does the implementation of that decorator and the dispatch logic look like? Are we registering the show functions in an index directory somewhere?","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"1714484865e0770fde73c53dfc42c17043238092","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_1199b178","line":205,"in_reply_to":"9aa7fdbe_77d948f2","updated":"2014-10-28 18:22:00.000000000","message":"This is what I meant by a registry:\n\n https://github.com/cyeoh/microversions_poc/blob/master/versioned_object.py#L107\n\nwhich makes sense to me. I\u0027m a little hesitant about the deleting of the original functions so that getattr is called, because I think it will be confusing to people. How about using __getattribute__ ?\n\n http://stackoverflow.com/questions/3278077/difference-between-getattr-vs-getattribute-in-python","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_77d948f2","line":205,"in_reply_to":"9aa7fdbe_d30a1678","updated":"2014-10-26 23:31:22.000000000","message":"No registration needed - just add the decorator. I have some POC code which is outside of Nova here:\n\nhttps://github.com/cyeoh/microversions_poc\n\nIts not meant to be a complete implementation (eg no exp, vendor flags etc, version comparison is a bit dodgy). It is separate from Nova because I think it makes it clearer how it works without requiring explicit registration which I think would be rather error prone.\n\nAnyway I\u0027d welcome any feedback at all about it.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"7e1cdb65241db73f616d9c092b0ce038a9c16fe1","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e       pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_fda7d7ba","line":205,"in_reply_to":"9aa7fdbe_d7caf419","updated":"2014-10-27 02:43:47.000000000","message":"I\u0027m begin to hate translation also. Now I\u0027m pretty like the way use nova object that I suggested at line 268 :)","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":221,"context_line":""},{"line_number":222,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1\u0027)"},{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e   pass"},{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_d3fcd674","line":224,"range":{"start_line":224,"start_character":4,"end_line":224,"end_character":8},"updated":"2014-10-24 19:44:05.000000000","message":"This needs indenting, even in python pseudocode :P","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"b3e5a63dbabb12e622262ea5a92751ff96d57c71","unresolved":false,"context_lines":[{"line_number":221,"context_line":""},{"line_number":222,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1\u0027)"},{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e   pass"},{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_f1a89b22","line":224,"in_reply_to":"9aa7fdbe_d3fcd674","updated":"2014-10-29 10:29:14.000000000","message":"Done","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"2cdc93fb4c13727b7b7847648502fb3c8a65ac75","unresolved":false,"context_lines":[{"line_number":229,"context_line":"\u003e"},{"line_number":230,"context_line":"\u003e   def show(self, req, id):"},{"line_number":231,"context_line":"\u003e      .... common stuff ...."},{"line_number":232,"context_line":"\u003e      self._version_specific_func(req, \"foo\")"},{"line_number":233,"context_line":"\u003e       .... common stuff ...."},{"line_number":234,"context_line":""},{"line_number":235,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_d06a2380","line":232,"updated":"2014-10-24 05:52:32.000000000","message":"I\u0027m not prefer to use versioned function for internal function like line 222. I prefer that before, but I found it isn\u0027t real readable. We have example before:\nhttps://review.openstack.org/#/c/82301/15/nova/api/openstack/compute/plugins/v3/hypervisors.py\n\nWe can only version the toplevel function. Maybe we can just use normal way to share code for internal function, like write some common function. Hope that can reduce the complex and magic of micro-version.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":229,"context_line":"\u003e"},{"line_number":230,"context_line":"\u003e   def show(self, req, id):"},{"line_number":231,"context_line":"\u003e      .... common stuff ...."},{"line_number":232,"context_line":"\u003e      self._version_specific_func(req, \"foo\")"},{"line_number":233,"context_line":"\u003e       .... common stuff ...."},{"line_number":234,"context_line":""},{"line_number":235,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_d7f1146c","line":232,"in_reply_to":"9aa7fdbe_73edeab6","updated":"2014-10-26 23:31:22.000000000","message":"So in general I\u0027d say yes. But I think I can see some cases where its useful. Eg say a 20 line method with just one line different right in the middle of the method.  Its basically a shortcut for doing an explicit version test like immediately below. \n\nAnyway there is no extra work needed to support this, and we can look at it on a case by case basis as to which option is clearer depending on the specific circumstance","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":229,"context_line":"\u003e"},{"line_number":230,"context_line":"\u003e   def show(self, req, id):"},{"line_number":231,"context_line":"\u003e      .... common stuff ...."},{"line_number":232,"context_line":"\u003e      self._version_specific_func(req, \"foo\")"},{"line_number":233,"context_line":"\u003e       .... common stuff ...."},{"line_number":234,"context_line":""},{"line_number":235,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_73edeab6","line":232,"in_reply_to":"9aa7fdbe_d06a2380","updated":"2014-10-24 19:44:05.000000000","message":"Yeah, seems like this is upside down. Have a common function (or functions) that the two versioned toplevels call, right?","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"2cdc93fb4c13727b7b7847648502fb3c8a65ac75","unresolved":false,"context_lines":[{"line_number":238,"context_line":""},{"line_number":239,"context_line":"A version object is passed down to the method attached to the request"},{"line_number":240,"context_line":"object so it is also possible to do very specific checks in a"},{"line_number":241,"context_line":"method. For example::"},{"line_number":242,"context_line":""},{"line_number":243,"context_line":"\u003e def show(self, req, id):"},{"line_number":244,"context_line":"\u003e    .... stuff ...."}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_b3f849c4","line":241,"updated":"2014-10-24 05:52:32.000000000","message":"Big +1 for version object","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"2cdc93fb4c13727b7b7847648502fb3c8a65ac75","unresolved":false,"context_lines":[{"line_number":265,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":266,"context_line":"versioning"},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_30344f92","line":268,"updated":"2014-10-24 05:52:32.000000000","message":"It isn\u0027t enough only implement versioning schema. Our API python code still need understand the response/request format. So we need something translate the response/request, but that reject by previous propose for v2 on v3, because it\u0027s too complex.\n\nNow I have two ideas:\n\n1. We can serialize/deserialize request and response as nova object. Then the multiple version changes for request/response hide in nova-object. like this https://github.com/openstack/nova/blob/master/nova/objects/instance.py#L206\nThis method need too much magic.\n\n2. https://github.com/soulxu/nova-v3-api-doc/commit/2d8489650ba221a3019b7db548ef8ce7a8a186dd\nGeneric it use mapping the request/response into flat dict by json-schema. Then we can provide versioning schema and needn\u0027t effect the API python code, and without another schema file for tranlsation. Detail at: http://soulxu.github.io/blog/2014/09/12/one-option-for-nova-api/","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"7e1cdb65241db73f616d9c092b0ce038a9c16fe1","unresolved":false,"context_lines":[{"line_number":265,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":266,"context_line":"versioning"},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_bdc2af50","line":268,"in_reply_to":"9aa7fdbe_179f1c04","updated":"2014-10-27 02:43:47.000000000","message":"Yes, What I\u0027m saying is same with you about have multiple schema definitions based on version.\n\nNow I little prefer to serialize/deserialize request and response as nova object, it isn\u0027t flat dict. And I think translation it must need some magic, I think use nova object way, it pretty simple and readable.\n\nBut I\u0027m looking forward your new way. Let see if you find better way.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":265,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":266,"context_line":"versioning"},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_179f1c04","line":268,"in_reply_to":"9aa7fdbe_30344f92","updated":"2014-10-26 23:31:22.000000000","message":"so what I am proposing is we have multiple schema definitions based on version. So if you request the 2.1 version you get the 2.1 schema test and if you request 3.2 you get the 3.2 schema test.\n\nserialisation doesn\u0027t avoid the multiple version support because although it may end up in a common dict format, it may still need to be interpreted differently in the method itself (eg handling of extra parameters). \n\nAs I mention above, I support translation, but I don\u0027t think translating to a common dict format is really any different to translating to the latest version instead.","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"b3e5a63dbabb12e622262ea5a92751ff96d57c71","unresolved":false,"context_lines":[{"line_number":265,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":266,"context_line":"versioning"},{"line_number":267,"context_line":""},{"line_number":268,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":""},{"line_number":271,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_4d765107","line":268,"in_reply_to":"9aa7fdbe_bdc2af50","updated":"2014-10-29 10:29:14.000000000","message":"So even converting to a nova object its still translation, just to a nova object instead of a dict, or to say the latest version representation.\n\nIf a parameter is added or removed it still doesn\u0027t (AFAICT) make the code any simpler, as we still need in-method calls to handle the cases where parameters may or may not be present.\n\nI can see it might save us a bit of in-method code in extraction, but any translation will do that.\n\nPerhaps you could add some pseudo code which compares having say translation to the latest version of the api versus translation to a nova object to demonstrate why it would be better (there will be overhead in defining all of these nova objects).","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"973a10a4f337f1d12cfca31b6d505731f4b91595","unresolved":false,"context_lines":[{"line_number":339,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":340,"context_line":"  it could be present."},{"line_number":341,"context_line":""},{"line_number":342,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":343,"context_line":""},{"line_number":344,"context_line":""},{"line_number":345,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_b3f59258","line":342,"updated":"2014-10-24 19:44:05.000000000","message":"I think we need an A to go with this Q :)","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"1714484865e0770fde73c53dfc42c17043238092","unresolved":false,"context_lines":[{"line_number":339,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":340,"context_line":"  it could be present."},{"line_number":341,"context_line":""},{"line_number":342,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":343,"context_line":""},{"line_number":344,"context_line":""},{"line_number":345,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_11a7f1a7","line":342,"in_reply_to":"9aa7fdbe_778788b5","updated":"2014-10-28 18:22:00.000000000","message":"Well, that\u0027s fine, I just think that regardless of what we decide, we should put that here as, this is a question with no answer (AFAICT), which isn\u0027t what I expect when I read an FAQ section :)","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1017e1b356060c671a0c856add76eb23de48e3a1","unresolved":false,"context_lines":[{"line_number":339,"context_line":"  I think we should still bump the minor number so they know if"},{"line_number":340,"context_line":"  it could be present."},{"line_number":341,"context_line":""},{"line_number":342,"context_line":"* Do we bump a version number when error status codes change?"},{"line_number":343,"context_line":""},{"line_number":344,"context_line":""},{"line_number":345,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"9aa7fdbe_778788b5","line":342,"in_reply_to":"9aa7fdbe_b3f59258","updated":"2014-10-26 23:31:22.000000000","message":"So we haven\u0027t in the past been considering status code changes as significant API changes, though some would like them to be considered a backwards incompatible one. And if people actually checked error codes in practice I\u0027d agree. But we\u0027ve been arbitrarily changing error codes for a few years now and AFAIK haven\u0027t received a single bug report about it. So I wonder if people actually do ever check them!","commit_id":"88b2b2320d461438502a7da830484d7a387f4a4f"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":58,"context_line":"  the REST API are able to decide if they want the Nova API to behave"},{"line_number":59,"context_line":"  in the new or old manner on a per request basis. Deployers"},{"line_number":60,"context_line":"  are able to make new backwards incompatible features available"},{"line_number":61,"context_line":"  without removing support for prior behaviour."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"* Users of the REST API are able to, on a per request basis, decide"},{"line_number":64,"context_line":"  which version of the API they want to use (assuming the deployer"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_d3eeeab3","line":61,"updated":"2014-11-06 07:53:08.000000000","message":"Note that it is a bit disingenuous to suggest that deployers of the API would have the power to make new backwards incompatible features available without removing support for prior behaviour. The reason is because it is up to the *developers* of Nova to decide when features are deprecated and removed from the Nova code base. So, while it is true that this framework will enable a deployer to continue to offer features for some amount of time, we also know that we want to actually clean up the Nova code base, and that means eventually deleting a whole bunch of cruft. And that means that developers are actually the ones that truly determine the boundaries of what a deployer can really offer.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":58,"context_line":"  the REST API are able to decide if they want the Nova API to behave"},{"line_number":59,"context_line":"  in the new or old manner on a per request basis. Deployers"},{"line_number":60,"context_line":"  are able to make new backwards incompatible features available"},{"line_number":61,"context_line":"  without removing support for prior behaviour."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"* Users of the REST API are able to, on a per request basis, decide"},{"line_number":64,"context_line":"  which version of the API they want to use (assuming the deployer"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_28451bb3","line":61,"in_reply_to":"7a8c0949_d3eeeab3","updated":"2014-11-12 04:34:01.000000000","message":"fair enough. I will clarify the statement.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":106,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":107,"context_line":"under the OpenStack API Change Guidelines"},{"line_number":108,"context_line":""},{"line_number":109,"context_line":"http://wiki.openstack.org/wiki/APIChangeGuidelines"},{"line_number":110,"context_line":""},{"line_number":111,"context_line":"A version response would look as follows"},{"line_number":112,"context_line":""}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_7340d6a5","line":109,"updated":"2014-11-06 07:53:08.000000000","message":"I disagree with a number of things in the above document, including the assertion that a change to an HTTP response code for failures is a backwards compatible change.\n\nBackwards compatible for who? Certainly not for SDK and tooling developers, which is really the audience we need to be concerned about.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":106,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":107,"context_line":"under the OpenStack API Change Guidelines"},{"line_number":108,"context_line":""},{"line_number":109,"context_line":"http://wiki.openstack.org/wiki/APIChangeGuidelines"},{"line_number":110,"context_line":""},{"line_number":111,"context_line":"A version response would look as follows"},{"line_number":112,"context_line":""}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_a8102ba9","line":109,"in_reply_to":"7a8c0949_7340d6a5","updated":"2014-11-12 04:34:01.000000000","message":"ok. I don\u0027t want to get into a debate here about what is backwards compatible and what is not as it is not really relevant to this spec. So just trying to punt it our current agreed upon guidelines and we can modify those if need be.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":114,"context_line":""},{"line_number":115,"context_line":"    GET /"},{"line_number":116,"context_line":"    {"},{"line_number":117,"context_line":"         \"versions\": ["},{"line_number":118,"context_line":"            {"},{"line_number":119,"context_line":"                \"id\": \"v2.1\","},{"line_number":120,"context_line":"                \"links\": ["}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_f313e6b5","line":117,"updated":"2014-11-06 07:53:08.000000000","message":"Why do we need the outer \"versions\" element or a list of versions?","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"da1a95bd64c20a98c6924c9196aa2eade19ed311","unresolved":false,"context_lines":[{"line_number":114,"context_line":""},{"line_number":115,"context_line":"    GET /"},{"line_number":116,"context_line":"    {"},{"line_number":117,"context_line":"         \"versions\": ["},{"line_number":118,"context_line":"            {"},{"line_number":119,"context_line":"                \"id\": \"v2.1\","},{"line_number":120,"context_line":"                \"links\": ["}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_5ebbe171","line":117,"in_reply_to":"7a8c0949_f313e6b5","updated":"2014-11-06 09:24:15.000000000","message":"That is current format of \"list versions\" API.\nIt is better to keep the format for backwards compatibility ;)","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":123,"context_line":"                        \"rel\": \"self\""},{"line_number":124,"context_line":"                    }"},{"line_number":125,"context_line":"                ],"},{"line_number":126,"context_line":"                \"status\": \"CURRENT\","},{"line_number":127,"context_line":"                \"version\": \"5.2\""},{"line_number":128,"context_line":"                \"min_version\": \"2.1\""},{"line_number":129,"context_line":"            },"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_53111aab","line":126,"updated":"2014-11-06 07:53:08.000000000","message":"What is the purpose of \"status\" being CURRENT any more? With this proposal, the only fields of worth are a max and min supported version...","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":123,"context_line":"                        \"rel\": \"self\""},{"line_number":124,"context_line":"                    }"},{"line_number":125,"context_line":"                ],"},{"line_number":126,"context_line":"                \"status\": \"CURRENT\","},{"line_number":127,"context_line":"                \"version\": \"5.2\""},{"line_number":128,"context_line":"                \"min_version\": \"2.1\""},{"line_number":129,"context_line":"            },"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_c8265716","line":126,"in_reply_to":"7a8c0949_53111aab","updated":"2014-11-12 04:34:01.000000000","message":"yep, though we probably need to keep this here to keep backwards compatibility for now. Can remove with a major microversions bump","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":158,"context_line":"  return 406 Not Acceptable."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"* If X-OpenStack-Compute-API-Version: latest (special keyword) return"},{"line_number":161,"context_line":"  max_version of the API."}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_f51fa7b5","line":158,"updated":"2014-10-30 08:10:10.000000000","message":"Nova needs to check both version X and version Y separately because needing to return 406 in the following case:\n\n Nova version: 5.10\n Client specifying version: 3.11","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":155,"context_line":""},{"line_number":156,"context_line":"* If X-OpenStack-Compute-API-Version is sent, respond with the API at that"},{"line_number":157,"context_line":"  version. If that\u0027s outside of the range of versions supported,"},{"line_number":158,"context_line":"  return 406 Not Acceptable."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"* If X-OpenStack-Compute-API-Version: latest (special keyword) return"},{"line_number":161,"context_line":"  max_version of the API."}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_e82153fd","line":158,"in_reply_to":"7a8c0949_f51fa7b5","updated":"2014-11-12 04:34:01.000000000","message":"yes it will be a semver comparison where 3.11 \u003c 5.10","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":161,"context_line":"  max_version of the API."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"* If experimental is sent, return results with *all* experimental"},{"line_number":164,"context_line":"  extensions enabled."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":167,"context_line":"  of tree vendor extensions."}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_335c8e7e","line":164,"updated":"2014-11-06 07:53:08.000000000","message":"-1 for API extensions. If the point of having microversions is to allow our APIs to be evolved over time (including backwards incompatible changes), then we need to get to the point where version X of an API means something consistent. With API extensions, that is not possible... because you would be publishing version X of the API **and all these other thingamabobs in API extensions**, so you\u0027ve now lost all ability of the version X to mean something consistent across multiple deployments of the Nova API.\nIMO, we need to make version 2.1.0 be the Nova API without any API extensions, and merge all the existing API extensions in the v2/v3 code into one single API, with version 2.1.0. Only then will we be able to make this blueprint\u0027s objectives a reality.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":161,"context_line":"  max_version of the API."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"* If experimental is sent, return results with *all* experimental"},{"line_number":164,"context_line":"  extensions enabled."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":167,"context_line":"  of tree vendor extensions."}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_a85e6b74","line":164,"in_reply_to":"7a8c0949_335c8e7e","updated":"2014-11-12 04:34:01.000000000","message":"Two points - the first is that experimental is quite important. We\u0027ve shown in the past we\u0027re not great at getting APIs perfect the first time around. So we want a mechanism to do release new APIs for a cycle without being bound to that API forever. After 1 cycle it\u0027ll become part of the stable API or dropped, but it will be clear to users that it is experimental. This is not unusual - eg Amazon release experimental APIs subject to backwards uncompatible change until marked as stable.\n\nHowever, where people never specify experimental it will be the same across all deployments.\n\nSecondly, regarding extensions, I think that is a step too far for v2.1.0 For starters v2.1.0 is meant to be exactly the same as v2 (so we can get rid of that code) which means deployers need to have the flexibility to not enable extensions just like they do now.  Also there is no consensus of whatever is in or out of a fixed API and we don\u0027t have time to wait for that to occur (nor has anyone been interested in trying to establish this consensus). We need microversions much sooner than this is going to happen.\n\nA fixed API can be established with a microversion bump when that consensus is established.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"6ab4695c8d7e5deef73539ec2dee66e1c5f1e04f","unresolved":false,"context_lines":[{"line_number":164,"context_line":"  extensions enabled."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":167,"context_line":"  of tree vendor extensions."},{"line_number":168,"context_line":""},{"line_number":169,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":170,"context_line":"installation will return vanilla OpenStack responses at v2. The user"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_b3215efd","line":167,"updated":"2014-11-06 07:53:08.000000000","message":"No. No vendor extensions or support.\n\nRecommend getting rid of the vendor: specification entirely. The point of standardizing our APIs is to make them standard, not to allow vendorization. API extensions were an idea designed (in part) to allow vendorization. And we\u0027ve seen how that works out.\n\nLet\u0027s take a hard stand and say \"this is the OpenStack Compute API\" and be done with it. If RAX or HP Cloud or Frobnozzle Cloud wants to have a separate but different API, then they should call it something else, because it\u0027s not the OpenStack Compute API.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":164,"context_line":"  extensions enabled."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":"* If vendor:VENDORNAMESPACE is sent, return results that include out"},{"line_number":167,"context_line":"  of tree vendor extensions."},{"line_number":168,"context_line":""},{"line_number":169,"context_line":"This means out of the box, with an old client, an OpenStack"},{"line_number":170,"context_line":"installation will return vanilla OpenStack responses at v2. The user"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_084f7fbe","line":167,"in_reply_to":"7a8c0949_b3215efd","updated":"2014-11-12 04:34:01.000000000","message":".... Or they\u0027ll modify it and just not say anything. At least where clients have to specify a flag they know what they\u0027re getting themselves into","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e     pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_35bccf6c","line":205,"updated":"2014-10-30 08:10:10.000000000","message":"I think Nova can provide extra(backwards compatible) attributes even if a client specifying version is smaller than Nova supported version.\nFor example, if the version history like\n\n 2.1: original\n 2.2: Add an attribute \"foo\" to a response\n\nand a client specifies version 2.1, nova return a response including an attribute \"foo\".\n\nIf that is right, I think we don\u0027t need to specify version Y in @api_version().","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"::"},{"line_number":204,"context_line":""},{"line_number":205,"context_line":"\u003e  @api_version(min_version\u003d\u00272.1\u0027, max_version\u003d\u00272.9\u0027)"},{"line_number":206,"context_line":"\u003e  def show(self, req, id):"},{"line_number":207,"context_line":"\u003e     pass"},{"line_number":208,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_48c8a722","line":205,"in_reply_to":"7a8c0949_35bccf6c","updated":"2014-11-12 04:34:01.000000000","message":"So we still need the Y version because clients need to be able to specify that foo will be returned in the response (eg they want 2.2 and not 2.1). So if they talk to cloud X and it only supports 2.1 and not 2.2 it can reject their request.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":210,"context_line":"\u003e  def show(self, req, id):"},{"line_number":211,"context_line":"\u003e     pass"},{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2.0 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1.0 of the API would result in the second being executed."},{"line_number":216,"context_line":""}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_f5a96725","line":213,"updated":"2014-10-30 08:10:10.000000000","message":"s/2.2.0/2.2/","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":210,"context_line":"\u003e  def show(self, req, id):"},{"line_number":211,"context_line":"\u003e     pass"},{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2.0 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1.0 of the API would result in the second being executed."},{"line_number":216,"context_line":""}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_68cba31e","line":213,"in_reply_to":"7a8c0949_f5a96725","updated":"2014-11-12 04:34:01.000000000","message":"Done","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2.0 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1.0 of the API would result in the second being executed."},{"line_number":216,"context_line":""},{"line_number":217,"context_line":"For cases where the method implementations are very similar with just"},{"line_number":218,"context_line":"minor differences a lot of duplicated code can be avoided by versioning"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_9572e3e3","line":215,"updated":"2014-10-30 08:10:10.000000000","message":"s/3.1.0/3.1/","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2.0 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1.0 of the API would result in the second being executed."},{"line_number":216,"context_line":""},{"line_number":217,"context_line":"For cases where the method implementations are very similar with just"},{"line_number":218,"context_line":"minor differences a lot of duplicated code can be avoided by versioning"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_88d28fd0","line":215,"in_reply_to":"7a8c0949_9572e3e3","updated":"2014-11-12 04:34:01.000000000","message":"Done","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":219,"context_line":"internal methods intead. For example::"},{"line_number":220,"context_line":""},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1\u0027)"},{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e      pass"},{"line_number":225,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_9549038e","line":222,"updated":"2014-10-30 08:10:10.000000000","message":"How about\n\n @api_version(version\u003d2)","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":219,"context_line":"internal methods intead. For example::"},{"line_number":220,"context_line":""},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"\u003e   @api_version(min_version\u003d\u00272.1\u0027)"},{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e      pass"},{"line_number":225,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_c8dbb7eb","line":222,"in_reply_to":"7a8c0949_9549038e","updated":"2014-11-12 04:34:01.000000000","message":"I don\u0027t think we can do that for the above reasons (~line205)","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e      pass"},{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":228,"context_line":"\u003e      pass"},{"line_number":229,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_d55aab4f","line":226,"updated":"2014-10-30 08:10:10.000000000","message":"and\n\n @api_version(min_version\u003d3)\n\n?","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":223,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":224,"context_line":"\u003e      pass"},{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":228,"context_line":"\u003e      pass"},{"line_number":229,"context_line":"\u003e"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_e8d6b3c2","line":226,"in_reply_to":"7a8c0949_d55aab4f","updated":"2014-11-12 04:34:01.000000000","message":"ditto","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac66cb1446d671e687ca6d53447cb86a371eb919","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":""},{"line_number":273,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_f854fecb","line":270,"updated":"2014-10-30 08:10:10.000000000","message":"The above schema() definition seems that we need to implement API schemas for each version X at least.\nThat will create duplicated code on the schemas and they are almost the same because of just renaming attributes etc.\n\nI think the reason of the previous v2.1 idea(translation) denial is that it would be difficult to debug problems because of a lot of translations.\nSo how about the following implementation?\n\n @api_version(version\u003d2)\n def _post_v2(self, req, id, body):\n     image_id \u003d body.pop(\u0027imageRef\u0027)\n     flavor_id \u003d body.pop(\u0027flavorRef\u0027)\n     body[\u0027image_ref\u0027] \u003d image_id\n     body[\u0027flavor_ref\u0027] \u003d flavor_id\n     response \u003d self._show_v4(req, id, body):\n     [..]\n\n @api_version(version\u003d3)             # Rename imageRef to image_ref\n def _post_v3(self, req, id, body):\n     flavor_id \u003d body.pop(\u0027flavorRef\u0027)\n     body[\u0027flavor_ref\u0027] \u003d flavor_id\n     response \u003d self._show_v4(req, id, body):\n     [..]\n\n @api_version(version\u003d4)            # Rename flavorRef to flavor_ref\n @validation(schema)\n def _show_v4(self, req, id):\n     [..]\n\nWe don\u0027t need to define similar schemas and can reduce duplicated code.\nDebugging would be easy also.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"927501ce687b710d5d1b2619335f673f61c89a99","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":""},{"line_number":273,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_983a1a35","line":270,"in_reply_to":"7a8c0949_58bb52c4","updated":"2014-10-30 08:27:43.000000000","message":"@Eli\n\nNice point. Yeah, my above idea is difficult to implement json discovery. So maybe we need duplicated schemas :-(","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"1b6beaa7f96c01f65f52bd123f9f29f35011f6e7","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":""},{"line_number":273,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":10,"id":"5a890539_28e19b9a","line":270,"in_reply_to":"7a8c0949_983a1a35","updated":"2014-11-12 04:34:01.000000000","message":"yep we need duplicated schemas for json discovery, or at least build upon a base schema like we already do.","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":12175,"name":"Eli Qiao","email":"qiaoliyong@gmail.com","username":"Eli"},"change_message_id":"76ca4d35f1518b657ca08e3ed9a154b1549c863b","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":""},{"line_number":273,"context_line":"Alternatives"}],"source_content_type":"text/x-rst","patch_set":10,"id":"7a8c0949_58bb52c4","line":270,"in_reply_to":"7a8c0949_f854fecb","updated":"2014-10-30 08:23:21.000000000","message":"too much hack.\nthis will make developer hard to read what changes ..\nand it will be diffcult to do json discovery. \nI think even we have duplicated json schema file, that is acceptable.\nwhat do you think?","commit_id":"4728370c030337c327a290d61bdd42eacfa0aec1"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"79b41c3cf0102c2319db2cb6b1463f8f7b5b8d45","unresolved":false,"context_lines":[{"line_number":98,"context_line":"optional extensions in the Nova tree."},{"line_number":99,"context_line":""},{"line_number":100,"context_line":"Versioning of the API should be a single monotonic counter. It will be"},{"line_number":101,"context_line":"of the form X.Y where it follows the Semantic Versioning 2.0.0"},{"line_number":102,"context_line":"specification (http://semver.org). Eg. you increment"},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"* X when you make incompatible API changes"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_0bc48bf3","line":101,"updated":"2014-11-14 04:01:31.000000000","message":"On the summit, the versioning is X.Y.Z and\n\n X: the fixed \"2\" for fitting the endpoint(v2/v2.1)\n Y: when you make incompatible API changes\n Z: when you make backwards compatible changes\n\nthat seems reasonable for me.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"ad342785e7359aede95efc739ffb9d95df5eddd2","unresolved":false,"context_lines":[{"line_number":98,"context_line":"optional extensions in the Nova tree."},{"line_number":99,"context_line":""},{"line_number":100,"context_line":"Versioning of the API should be a single monotonic counter. It will be"},{"line_number":101,"context_line":"of the form X.Y where it follows the Semantic Versioning 2.0.0"},{"line_number":102,"context_line":"specification (http://semver.org). Eg. you increment"},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"* X when you make incompatible API changes"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_ceb45137","line":101,"in_reply_to":"5a890539_0bc48bf3","updated":"2014-11-14 04:21:45.000000000","message":"isn\u0027t version X kind of pointless linking it to the url path? Given we want to get rid of the versioned endpoint anyway. Also proxies can already change the path so from a users point of view they may not always match","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"cb21dc44111363581464257316c9fd756d7fb262","unresolved":false,"context_lines":[{"line_number":102,"context_line":"specification (http://semver.org). Eg. you increment"},{"line_number":103,"context_line":""},{"line_number":104,"context_line":"* X when you make incompatible API changes"},{"line_number":105,"context_line":"* Y when you make backwards compatible changes"},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"A backwards compatible change is defined as one which would be allowed"},{"line_number":108,"context_line":"under the OpenStack API Change Guidelines"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_8b1f9b07","line":105,"updated":"2014-11-14 03:41:41.000000000","message":"we should clarify we bump the version for every single change. Not a set of similar change.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"cb21dc44111363581464257316c9fd756d7fb262","unresolved":false,"context_lines":[{"line_number":174,"context_line":""},{"line_number":175,"context_line":"Experimental as a flag also is introduced as a *deprecated* construct,"},{"line_number":176,"context_line":"with removal of the infrastructure to support it in a coutable number"},{"line_number":177,"context_line":"of releases. This is designed as a transitional mechanism."},{"line_number":178,"context_line":""},{"line_number":179,"context_line":"Implementation design details"},{"line_number":180,"context_line":"-----------------------------"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_ebbc9fde","line":177,"updated":"2014-11-14 03:41:41.000000000","message":"When experimental extension become formal, how we can bump the version? Bump one version for one extension, I guess? We should maintenance a version list, like https://github.com/openstack/nova/blob/master/nova/objects/instance.py#L79","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f7d8d01df82ff804cc4e1e351e8085e69c56b982","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1 of the API would result in the second being executed."},{"line_number":216,"context_line":""},{"line_number":217,"context_line":"For cases where the method implementations are very similar with just"},{"line_number":218,"context_line":"minor differences a lot of duplicated code can be avoided by versioning"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_5e2bdd2f","line":215,"updated":"2014-11-13 07:07:42.000000000","message":"3.1 -\u003e 3.0 as in above pseudo code (L209), max_version will be treated as \u00273.0\u0027. right?","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"7289a2b1b6f80018fde71264eed643c955462066","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"An incoming request for version 2.2 of the API would end up"},{"line_number":214,"context_line":"executing the first method, whilst an incoming request for version"},{"line_number":215,"context_line":"3.1 of the API would result in the second being executed."},{"line_number":216,"context_line":""},{"line_number":217,"context_line":"For cases where the method implementations are very similar with just"},{"line_number":218,"context_line":"minor differences a lot of duplicated code can be avoided by versioning"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_ab7c58b6","line":215,"in_reply_to":"5a890539_5e2bdd2f","updated":"2014-11-14 04:08:09.000000000","message":"no there is no maximimum version in the example above. So any request for a version above minimum version will result in this version of the function being called.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f7d8d01df82ff804cc4e1e351e8085e69c56b982","unresolved":false,"context_lines":[{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":228,"context_line":"\u003e      pass"},{"line_number":229,"context_line":"\u003e"},{"line_number":230,"context_line":"\u003e   def show(self, req, id):"},{"line_number":231,"context_line":"\u003e      .... common stuff ...."}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_fe5f29e3","line":228,"updated":"2014-11-13 07:07:42.000000000","message":"are we going to have different code base/function for y versions too?\n\nCan we keep modifying the original function in case of Y version bump as it is backward compatible? As per L295, new backward compatible changes can be returned in older Y version.\nAnd in case of X version bump (backward compatible)  we can have separate function(main or internal function based on code changes)","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"7289a2b1b6f80018fde71264eed643c955462066","unresolved":false,"context_lines":[{"line_number":225,"context_line":"\u003e"},{"line_number":226,"context_line":"\u003e   @api_version(min_version\u003d\u00272.5\u0027)"},{"line_number":227,"context_line":"\u003e   def _version_specific_func(self, req, arg1):"},{"line_number":228,"context_line":"\u003e      pass"},{"line_number":229,"context_line":"\u003e"},{"line_number":230,"context_line":"\u003e   def show(self, req, id):"},{"line_number":231,"context_line":"\u003e      .... common stuff ...."}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_0b2e4b92","line":228,"in_reply_to":"5a890539_fe5f29e3","updated":"2014-11-14 04:08:09.000000000","message":"yes thats possible but we don\u0027t need to necessarily do it on that basis. For example if the backwards incompatible change is only a two line change in a large function, can use if req.ver_obj.match(3.0) within this function. I think it depends at the time what looks more maintenable vs code duplication","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f7d8d01df82ff804cc4e1e351e8085e69c56b982","unresolved":false,"context_lines":[{"line_number":255,"context_line":"vendor specific it can be marked with:"},{"line_number":256,"context_line":""},{"line_number":257,"context_line":"@api_exp()"},{"line_number":258,"context_line":"@api_vendor(\"vendor_string\")"},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"Note that you cannot combine these with the api_version decorator or"},{"line_number":261,"context_line":"with each other."}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_bea041a0","line":258,"updated":"2014-11-13 07:07:42.000000000","message":"nit-v we can remove vendor now.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"7289a2b1b6f80018fde71264eed643c955462066","unresolved":false,"context_lines":[{"line_number":255,"context_line":"vendor specific it can be marked with:"},{"line_number":256,"context_line":""},{"line_number":257,"context_line":"@api_exp()"},{"line_number":258,"context_line":"@api_vendor(\"vendor_string\")"},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"Note that you cannot combine these with the api_version decorator or"},{"line_number":261,"context_line":"with each other."}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_2b1f875c","line":258,"in_reply_to":"5a890539_7c6a4082","updated":"2014-11-14 04:08:09.000000000","message":"Done","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"cdac5dd48475705d0db7f4ea22c0c470fc131013","unresolved":false,"context_lines":[{"line_number":255,"context_line":"vendor specific it can be marked with:"},{"line_number":256,"context_line":""},{"line_number":257,"context_line":"@api_exp()"},{"line_number":258,"context_line":"@api_vendor(\"vendor_string\")"},{"line_number":259,"context_line":""},{"line_number":260,"context_line":"Note that you cannot combine these with the api_version decorator or"},{"line_number":261,"context_line":"with each other."}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_7c6a4082","line":258,"in_reply_to":"5a890539_bea041a0","updated":"2014-11-13 22:51:44.000000000","message":"Yep.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"cb21dc44111363581464257316c9fd756d7fb262","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":"A method, extension, or a field in a request or response can be"},{"line_number":273,"context_line":"removed from the API by specifying a max_version. Since it is a"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_abab7773","line":270,"updated":"2014-11-14 03:41:41.000000000","message":"We needn\u0027t extend the schema decorator. We already have decorator @api_version(min_version\u003d\u00272.1\u0027) take the version info.","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"7289a2b1b6f80018fde71264eed643c955462066","unresolved":false,"context_lines":[{"line_number":267,"context_line":"The validation schema decorator would also need to be extended to support"},{"line_number":268,"context_line":"versioning"},{"line_number":269,"context_line":""},{"line_number":270,"context_line":"@validation.schema(schema_definition, min_version, max_version)"},{"line_number":271,"context_line":""},{"line_number":272,"context_line":"A method, extension, or a field in a request or response can be"},{"line_number":273,"context_line":"removed from the API by specifying a max_version. Since it is a"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_8bda3be6","line":270,"in_reply_to":"5a890539_abab7773","updated":"2014-11-14 04:08:09.000000000","message":"the schema may be different depending on the version. In that case we do need a versioned schema decorator\n\nmin and max will be optional","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":12898,"name":"Tony Breeds","email":"tony@bakeyournoodle.com","username":"tonyb"},"change_message_id":"ae7e5bd02243ec8355d0a347b0981f690a161f18","unresolved":false,"context_lines":[{"line_number":287,"context_line":"backwards compatibility forever."},{"line_number":288,"context_line":""},{"line_number":289,"context_line":"Because we have a monotonically increasing version number across the"},{"line_number":290,"context_line":"whole of the API rather than versioning individual plgins we will have"},{"line_number":291,"context_line":"potential merge conflicts like we currenty have with DB migration"},{"line_number":292,"context_line":"changesets. Sorry, I don\u0027t believe there is any way around this, but"},{"line_number":293,"context_line":"welcome any suggestions!"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_abfa9740","line":290,"updated":"2014-11-14 03:58:53.000000000","message":"nit *plugins*","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"ad342785e7359aede95efc739ffb9d95df5eddd2","unresolved":false,"context_lines":[{"line_number":287,"context_line":"backwards compatibility forever."},{"line_number":288,"context_line":""},{"line_number":289,"context_line":"Because we have a monotonically increasing version number across the"},{"line_number":290,"context_line":"whole of the API rather than versioning individual plgins we will have"},{"line_number":291,"context_line":"potential merge conflicts like we currenty have with DB migration"},{"line_number":292,"context_line":"changesets. Sorry, I don\u0027t believe there is any way around this, but"},{"line_number":293,"context_line":"welcome any suggestions!"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_4e806146","line":290,"in_reply_to":"5a890539_abfa9740","updated":"2014-11-14 04:21:45.000000000","message":"Done","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"cb21dc44111363581464257316c9fd756d7fb262","unresolved":false,"context_lines":[{"line_number":297,"context_line":"reduce test coverage required. However we do need to retain the"},{"line_number":298,"context_line":"ability for a client to specify version 3.3 as the server they are"},{"line_number":299,"context_line":"talking to may only support up to 3.2 and the client needs to be told"},{"line_number":300,"context_line":"they are asking for an unsupported version."},{"line_number":301,"context_line":""},{"line_number":302,"context_line":""},{"line_number":303,"context_line":"Client Expectations"}],"source_content_type":"text/x-rst","patch_set":12,"id":"5a890539_0be56bdc","line":300,"updated":"2014-11-14 03:41:41.000000000","message":"Big +1","commit_id":"b6cd0a4487585ac2128bb9580f29ea451ec26755"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"6b8530dba3d17b8864ad7279c15945255e423b18","unresolved":false,"context_lines":[{"line_number":330,"context_line":"talks to multiple clouds."},{"line_number":331,"context_line":""},{"line_number":332,"context_line":"The concrete example is nodepool in OpenStack Infra. Assume there is a"},{"line_number":333,"context_line":"world where it is regularlly connecting to 4 public clouds. They are"},{"line_number":334,"context_line":"at the following states::"},{"line_number":335,"context_line":""},{"line_number":336,"context_line":"  - Cloud A:"}],"source_content_type":"text/x-rst","patch_set":18,"id":"5a890539_4de495ab","line":333,"range":{"start_line":333,"start_character":18,"end_line":333,"end_character":28},"updated":"2014-11-18 01:10:59.000000000","message":"\"regularly\" is misspelled","commit_id":"2e17bfe3c753c49980ad54fa77321a924187e97a"},{"author":{"_account_id":4393,"name":"Dan Smith","email":"dms@danplanet.com","username":"danms"},"change_message_id":"b6553ea9a50d1ac190fe724cef155f708e02b02c","unresolved":false,"context_lines":[{"line_number":100,"context_line":"Versioning of the API should be a single monotonic counter. It will be"},{"line_number":101,"context_line":"of the form X.Y where it follows the following convention:"},{"line_number":102,"context_line":""},{"line_number":103,"context_line":"* X will only be changed if a significant backwards incomaptible"},{"line_number":104,"context_line":"  API change is made which affects the API as whole. That is, something"},{"line_number":105,"context_line":"  that is only very very rarely incremented."},{"line_number":106,"context_line":"* Y when you make any change to the API. Note that this includes"}],"source_content_type":"text/x-rst","patch_set":19,"id":"5a890539_ad6979fa","line":103,"range":{"start_line":103,"start_character":52,"end_line":103,"end_character":64},"updated":"2014-11-18 01:18:23.000000000","message":"\"incompatible\" is misspelled.","commit_id":"dc6c4bcf0052c2f82bc7d96f19507b68859e5ede"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"5b4d8f0a853cf62b54f329a90e1583b05f37ec9e","unresolved":false,"context_lines":[{"line_number":109,"context_line":"  between backwards compatible and backwards incompatible changes in"},{"line_number":110,"context_line":"  the versioning system. It will however be made clear in the"},{"line_number":111,"context_line":"  documentation as to what is a backwards compatible change and what"},{"line_number":112,"context_line":"  is a backwards incompatible one."},{"line_number":113,"context_line":""},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"Note that groups of similar changes across the API will not be made"}],"source_content_type":"text/x-rst","patch_set":20,"id":"5a890539_6eece7bb","line":112,"updated":"2014-11-18 04:12:24.000000000","message":"This version Y seems a big change since previous spec, but this would make Nova API interface simple. +1","commit_id":"fa650a33174f8dd854a818a9f158e61139065769"},{"author":{"_account_id":5441,"name":"Andrew Laski","email":"andrew@lascii.com","username":"alaski"},"change_message_id":"fa5665c688ab4c8cc6f166439e1621465bd50bfc","unresolved":false,"context_lines":[{"line_number":158,"context_line":"  X-OpenStack-Compute-API-Version: 2.114, experimental"},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"This conceptually acts like the accept header.  We introduce 2"},{"line_number":161,"context_line":"concepts here, global API version and experimental flag."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"Semantically this means:"},{"line_number":164,"context_line":""}],"source_content_type":"text/x-rst","patch_set":20,"id":"5a890539_93284d34","line":161,"updated":"2014-11-18 14:24:10.000000000","message":"I thought we decided to drop the experimental flag?  Transitions for out of tree stuff from 2 -\u003e 2.x would add a \u0027tainted\u0027 flag to the response or something.  But clients wouldn\u0027t be able to request out of tree stuff.","commit_id":"fa650a33174f8dd854a818a9f158e61139065769"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"d2fe1334c677432fa0599c0729453226ce060f7d","unresolved":false,"context_lines":[{"line_number":71,"context_line":"The kilo priorities list is currently not defined. However under the"},{"line_number":72,"context_line":"currently proposed list of priorities it would fall under \"User"},{"line_number":73,"context_line":"Experience\" as it significantly increases the ability for us to"},{"line_number":74,"context_line":"improve the Nova API."},{"line_number":75,"context_line":""},{"line_number":76,"context_line":"Proposed change"},{"line_number":77,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":21,"id":"5a890539_30911d53","line":74,"updated":"2014-11-19 16:48:49.000000000","message":"We can update this very soon, an its on the list, but lets ignore that for now.","commit_id":"ee55e1cf3743b4660d99b532fac0eaab092749d2"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"d2fe1334c677432fa0599c0729453226ce060f7d","unresolved":false,"context_lines":[{"line_number":187,"context_line":"modification to the API behaviour that is non standard. This is only"},{"line_number":188,"context_line":"intended to be a transitional mechanism while some functionality used"},{"line_number":189,"context_line":"by cloud operators is upstreamed and it will be removed within a small"},{"line_number":190,"context_line":"number of releases.."},{"line_number":191,"context_line":""},{"line_number":192,"context_line":"The second header is used as a hint to caching proxies that the"},{"line_number":193,"context_line":"response is also dependent on the X-Openstack-Compute-API-Version and"}],"source_content_type":"text/x-rst","patch_set":21,"id":"5a890539_538f9375","line":190,"updated":"2014-11-19 16:48:49.000000000","message":"extra punctuation here, but not a big deal.","commit_id":"ee55e1cf3743b4660d99b532fac0eaab092749d2"},{"author":{"_account_id":12175,"name":"Eli Qiao","email":"qiaoliyong@gmail.com","username":"Eli"},"change_message_id":"b79e6b2071d39fc5a680b0fd8590f8d9d1ada925","unresolved":false,"context_lines":[{"line_number":435,"context_line":"* Implement APIVersions class"},{"line_number":436,"context_line":"* Implement handling of X-OpenStack-Compute-API-Version header"},{"line_number":437,"context_line":"* Implement routing of methods called based on version header."},{"line_number":438,"context_line":"* Find and implement first API change requiring a microversion bump."},{"line_number":439,"context_line":""},{"line_number":440,"context_line":""},{"line_number":441,"context_line":"Dependencies"}],"source_content_type":"text/x-rst","patch_set":21,"id":"5a890539_0a4de1c4","line":438,"updated":"2014-11-19 04:48:38.000000000","message":"I\u0027d like to advise this as the first API chages  https://etherpad.openstack.org/p/kilo-nova-microversions","commit_id":"ee55e1cf3743b4660d99b532fac0eaab092749d2"}]}