)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":30,"context_line":"have been removed as they were quite old thus not necessarily"},{"line_number":31,"context_line":"reflecting modern perspectives of OpenStack. They also made the"},{"line_number":32,"context_line":"document quite long and the current closing paragraph provides good"},{"line_number":33,"context_line":"code for while this all matters."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"[1] http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_cha"},{"line_number":36,"context_line":"nges.html added in I5485970686e352d5146bcfe2a3cf53388b929b04"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":4,"id":"da36d5c6_7a41410b","line":33,"range":{"start_line":33,"start_character":9,"end_line":33,"end_character":14},"updated":"2017-02-22 05:26:34.000000000","message":"why*","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":30,"context_line":"have been removed as they were quite old thus not necessarily"},{"line_number":31,"context_line":"reflecting modern perspectives of OpenStack. They also made the"},{"line_number":32,"context_line":"document quite long and the current closing paragraph provides good"},{"line_number":33,"context_line":"code for while this all matters."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"[1] http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_cha"},{"line_number":36,"context_line":"nges.html added in I5485970686e352d5146bcfe2a3cf53388b929b04"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":4,"id":"ba2be162_86536616","line":33,"in_reply_to":"da36d5c6_7a41410b","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":32,"context_line":"document quite long and the current closing paragraph provides good"},{"line_number":33,"context_line":"code for while this all matters."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"[1] http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_cha"},{"line_number":36,"context_line":"nges.html added in I5485970686e352d5146bcfe2a3cf53388b929b04"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"[2] https://wiki.openstack.org/w/index.php?title\u003dAPIChangeGuidelines\u0026action\u003dhistory"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":4,"id":"da36d5c6_da6f8d90","line":35,"updated":"2017-02-22 05:26:34.000000000","message":"link is broken by the newline","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":32,"context_line":"document quite long and the current closing paragraph provides good"},{"line_number":33,"context_line":"code for while this all matters."},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"[1] http://specs.openstack.org/openstack/api-wg/guidelines/evaluating_api_cha"},{"line_number":36,"context_line":"nges.html added in I5485970686e352d5146bcfe2a3cf53388b929b04"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"[2] https://wiki.openstack.org/w/index.php?title\u003dAPIChangeGuidelines\u0026action\u003dhistory"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":4,"id":"ba2be162_a656aa03","line":35,"in_reply_to":"da36d5c6_da6f8d90","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"}],"guidelines/api_compatibility.rst":[{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_ff86d9d9","line":37,"range":{"start_line":37,"start_character":35,"end_line":37,"end_character":55},"updated":"2017-01-26 22:58:23.000000000","message":"The use of squishy language contributes, and the fact that this has been labeled as a guideline, contributes to the issue raised by this review and a proposed tag related to API stability. Consider more concrete language here.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_d917d9a0","line":37,"in_reply_to":"3a461143_1e0a398a","updated":"2017-02-01 07:42:20.000000000","message":"+1, if new tag is going to be in place means projects have option to skip these guidelines, then it make sense to use MUST and MUST NOT here.\n\nProjects do not adopt that new tag then it\u0027s upto them how many of these guidelines they take or ignore.\n\nSo from tag perspective it has to be very clear on what is OK and what NOT and from point of view of api-wg guidelines, its just guidance and its upto projects that how much they follow.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_3a9e2107","line":37,"in_reply_to":"3a461143_7b24f6c5","updated":"2017-02-08 22:59:16.000000000","message":"So if it\u0027s all or nothing to get the tag, then let\u0027s go further and stop calling them \"guidelines\", and start calling them \"rules\". To get the tag, you must follow these rules. No squishiness needed.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"2368196c38165830f6aad1cc32680c1da289d166","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_7b24f6c5","line":37,"in_reply_to":"3a461143_d917d9a0","updated":"2017-02-02 17:56:28.000000000","message":"Agreed. Having the api-compatibility tag means following the guidelines as written.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"caadaf423bc57843bd13ffdb4c2e856e179024af","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_804ad1c3","line":37,"range":{"start_line":37,"start_character":35,"end_line":37,"end_character":55},"in_reply_to":"3a461143_ff86d9d9","updated":"2017-01-27 01:42:43.000000000","message":"+1, nice to have more concrete word as the guideline.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"14e6ed3f0533042fb3f5ce675218e17e5ffb6f30","unresolved":false,"context_lines":[{"line_number":34,"context_line":"Guidance"},{"line_number":35,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_1e0a398a","line":37,"in_reply_to":"3a461143_ff86d9d9","updated":"2017-01-31 18:48:37.000000000","message":"I agree that \"squish language\" is a frequent problem, but at least in the context of the api-wg the guidelines are exactly that: \"guidance\" that project can choose to follow or not.\n\nWhere I can see this integrating nicely with the proposed api-compatibility tag is that choosing to use the tag means choosing to follow this guidance.\n\nIf that\u0027s the case then the guidance does have to be black and white with MUST and MOST NOT instead of should, prefaced with \"if you choose to follow this, follow all of it\".\n\nYes or no?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":308,"name":"Thierry Carrez","email":"thierry@openstack.org","username":"ttx"},"change_message_id":"37fa40b43673ddbb2b3ef13594ea2fcf97a2fc28","unresolved":false,"context_lines":[{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_61e88311","line":39,"updated":"2017-01-20 13:28:35.000000000","message":"I think this opens a door that may be too wide. Of course this would be acceptable for an hypothetical extremely serious vulnerability where breaking the API is the one and only way to solve the issue. But security is always a trade-off, and sometimes fixing the \"security bug\" is not worth the breakage introduced.\n\nI would change that to \"the change is fixing a serious security issue, and the Vulnerability Management Team agrees that it is the only way to fix it\". That leaves examining the trade-off to a third-party trained in assessing those trade-offs. It should be rare enough cases anyway.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_3a3aa1e7","line":39,"in_reply_to":"3a461143_3957fd58","updated":"2017-02-08 22:59:16.000000000","message":"The problem here is what determines if a security bug is serious enough to justify making a breaking change to the API. So it makes sense to have a judge for this, and the VMT is a perfect choice.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_3957fd58","line":39,"in_reply_to":"3a461143_bc345ffb","updated":"2017-02-01 07:42:20.000000000","message":"+1 to define more boundary here and VTM agreement makes it more defined.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ab0d5abb068c51dfe65c09fcc1752cbad0152835","unresolved":false,"context_lines":[{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_96026d0a","line":39,"in_reply_to":"5a3905b3_61e88311","updated":"2017-01-24 20:24:03.000000000","message":"I prefer this as the first on the list.\nYeah, it is nice to make the use case small as possible.\nThierry\u0027s suggestion seems better for me.\n\nI guess CVE issues can be candidates for this case, but we cannot see CVE bug reports if that is still under fixing, not fixed.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":36,"context_line":""},{"line_number":37,"context_line":"The following types of changes are generally considered acceptable:"},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_bc345ffb","line":39,"in_reply_to":"5a3905b3_96026d0a","updated":"2017-01-26 22:58:23.000000000","message":"For the reasons noted above, as well as to ensure the proper context is set, this item should be treated separately further down the document.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"a4661079c9149a34072370b6df6e877afa5c3d5b","unresolved":false,"context_lines":[{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_6b053244","line":42,"updated":"2017-01-18 14:21:55.000000000","message":"Is this in the old guideline, or created for this new one? We\u0027ve generally not being doing this in strict versioning.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ab0d5abb068c51dfe65c09fcc1752cbad0152835","unresolved":false,"context_lines":[{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_794a5257","line":42,"in_reply_to":"7a3c09a3_26599f8e","updated":"2017-01-24 20:24:03.000000000","message":"I am fine to keep this line because of backwards compatibility.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1ce992f1a91cb889470006c06e7bec55e98a0cdf","unresolved":false,"context_lines":[{"line_number":39,"context_line":"* The change is the only way to fix a security bug."},{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_26599f8e","line":42,"in_reply_to":"7a3c09a3_6b053244","updated":"2017-01-18 14:35:26.000000000","message":"In patchset 1 this is a direct copy of the original, except for the warning (and title) above, so yeah this probably needs to be gone.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"a4661079c9149a34072370b6df6e877afa5c3d5b","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_ab92baf3","line":43,"updated":"2017-01-18 14:21:55.000000000","message":"We\u0027ve generally avoided this without some signaling to the user.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_7d234356","line":43,"in_reply_to":"3a461143_5923e9bc","updated":"2017-02-08 22:59:16.000000000","message":"A 5xx response is *never* expected by the user, by definition. If the request had any sort of error, a 4xx response would deal with that error. So changing a 5xx response isn\u0027t changing the API; it\u0027s fixing your broken application.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"14e6ed3f0533042fb3f5ce675218e17e5ffb6f30","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_de48b1b5","line":43,"in_reply_to":"3a461143_7fd749ed","updated":"2017-01-31 18:48:37.000000000","message":"\"Codifying a pattern for signaling would be valuable here.\"\n\nThis, I think, is a crux of the discusion. We keep saying we are talking about being stable or maintaining compatibility but then we what end up actually talking about are what things must cause a version boundary and how to signal that boundary.\n\nThat\u0027s a significant problem. If we claim to be talking about one thing, but then end up talking about another we need to make some adjustments.\n\nWithout resolving that it could be hard to make progress on the document.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_5923e9bc","line":43,"in_reply_to":"3a461143_de48b1b5","updated":"2017-02-01 07:42:20.000000000","message":"yea this area is always with different opinion all the time. But fixing 500 to more appropriate code is always nice but changing 400\u003d\u003e403 or something else can be problematic ?\n\nIMO fixing 500 case it acceptable and other not.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ab0d5abb068c51dfe65c09fcc1752cbad0152835","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_995e1e11","line":43,"in_reply_to":"5a3905b3_5610054f","updated":"2017-01-24 20:24:03.000000000","message":"How about treating original HTTP500 cases?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_3f2141b5","line":43,"in_reply_to":"5a3905b3_5610054f","updated":"2017-01-26 22:58:23.000000000","message":"This seems like an unjustified point of view. Is there some case for a cloud-dev or other API user to intentionally send (for example) a BadRequest and look for a 400 response? I\u0027m not saying there isn\u0027t but please make the case. If something didn\u0027t work, why does it need to fail in the same way? We should include that thinking.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_bf8b711d","line":43,"in_reply_to":"5a3905b3_995e1e11","updated":"2017-01-26 22:58:23.000000000","message":"It is critical to allow 5xx class errors to evolve toward 4xx class errors when appropriate. Changing \u0027an error response code\u0027 to more precise language would solve this.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_7fd749ed","line":43,"in_reply_to":"7a3c09a3_ab92baf3","updated":"2017-01-26 22:58:23.000000000","message":"Codifying a pattern for signaling would be valuable here.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5196,"name":"Matthew Treinish","email":"mtreinish@kortar.org","username":"treinish"},"change_message_id":"c2d30ecca2d5d50fc82fbc68e8809b4d66492473","unresolved":false,"context_lines":[{"line_number":40,"context_line":"* Fixing a bug so that a request which resulted in an error response before"},{"line_number":41,"context_line":"  is now successful."},{"line_number":42,"context_line":"* Adding a new response header."},{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_5610054f","line":43,"in_reply_to":"7a3c09a3_ab92baf3","updated":"2017-01-19 06:19:18.000000000","message":"I agree this is the same as changing a success code from my POV and it should be treated the same way.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":17716,"name":"Luz Cazares","email":"luz.cazares@intel.com","username":"luzcazares"},"change_message_id":"03fa904c7d3ce6c086a9bfc61b29f6d6710157b6","unresolved":false,"context_lines":[{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"},{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_176cf733","line":46,"range":{"start_line":46,"start_character":4,"end_line":46,"end_character":17},"updated":"2017-01-23 20:28:40.000000000","message":"does criteria applies also to microversions?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ab0d5abb068c51dfe65c09fcc1752cbad0152835","unresolved":false,"context_lines":[{"line_number":43,"context_line":"* Changing an error response code to be more accurate."},{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"},{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_99e37e33","line":46,"range":{"start_line":46,"start_character":4,"end_line":46,"end_character":17},"in_reply_to":"5a3905b3_176cf733","updated":"2017-01-24 20:24:03.000000000","message":"ah, nice catch.\nAt least, this \"API extension\" should be changed to \"API version\" because we have gotten a consensus to drop API extensions already.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":45,"context_line":"The following types of changes are acceptable when conditionally added as a"},{"line_number":46,"context_line":"new API extension:"},{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_9de54f0a","line":48,"updated":"2017-02-08 22:59:16.000000000","message":"This is also considered a breaking change, as some clients might iterate over the resource properties and break when they encounter an unknown property.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"a4661079c9149a34072370b6df6e877afa5c3d5b","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_4bd316d5","line":50,"updated":"2017-01-18 14:21:55.000000000","message":"If we are updating this for a modern era, we should probably really pull out the extensions language. As a community we\u0027ve swung the other way on this one having seen how crazy things get in the wild with API extensions.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_9929d19d","line":50,"in_reply_to":"5a3905b3_b69a09c4","updated":"2017-02-01 07:42:20.000000000","message":"+1","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5196,"name":"Matthew Treinish","email":"mtreinish@kortar.org","username":"treinish"},"change_message_id":"c2d30ecca2d5d50fc82fbc68e8809b4d66492473","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_b69a09c4","line":50,"in_reply_to":"7a3c09a3_2b432714","updated":"2017-01-19 06:19:18.000000000","message":"Yeah, all of the extensions language could just be replaced with version boundaries. Using extensions (or similar mechanism) as a version control is not something we should encourage. I think microversions is the right approach, but do we want to encode that here?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"2a29297bb07c39bfab322d4321f88c8a9925d520","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_c87629a3","line":50,"in_reply_to":"7a3c09a3_4bd316d5","updated":"2017-01-18 14:55:33.000000000","message":"+1 for what it\u0027s worth, in keystone we introduce what would be extensions as official APIs and mark them as `experimental`. A few releases back we went through and migrated all our extensions to be official keystone bits and re-evaluated their status as being either `stable` or `experimental`.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"340aeac3834b1b488446352b7e3d5e0392a3002c","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"* Adding a property to a resource representation."},{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_2b432714","line":50,"in_reply_to":"7a3c09a3_c87629a3","updated":"2017-01-18 15:01:22.000000000","message":"Some more context on how keystone does some of this [0]. \n\n[0] https://github.com/openstack/keystone/blob/fab399e26cdbe7cffba895f99d7247896ec6cb82/keystone/common/json_home.py#L61-L63","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5314,"name":"Brian Rosmaita","email":"rosmaita.fossdev@gmail.com","username":"brian-rosmaita"},"change_message_id":"2ff6db2658b339eb32589a0d523d9a5700b1b668","unresolved":false,"context_lines":[{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_d9269d67","line":52,"range":{"start_line":52,"start_character":35,"end_line":52,"end_character":44},"updated":"2017-01-26 21:32:38.000000000","message":"Here\u0027s my problem with this document.  By saying \"generally\", it\u0027s implied that these are not hard-and-fast rules, but that there can be exceptions.  Which is fine, if that\u0027s the way we want to go.  But in that case, it must be made clear what the adjudication process is.  Does the API-WG have the final say? The QA team? The TC?  It\u0027s not clear right now, and that\u0027s been a big problem for Glance this cycle.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_240b5425","line":52,"in_reply_to":"3a461143_1e9b1919","updated":"2017-02-01 07:42:20.000000000","message":"+1 on that.\nif no consensus(qa \u0026 api-wg):\n    return TC decision\n\nI feel that should be written in tag guidelines doc - https://review.openstack.org/#/c/418010/\n\ntag is something which can force these guidelines as Must or Must Not","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_5dada799","line":52,"in_reply_to":"3a461143_240b5425","updated":"2017-02-08 22:59:16.000000000","message":"+1 for removing \"generally\".\n+1 for specifying the process for resolving issues.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"14e6ed3f0533042fb3f5ce675218e17e5ffb6f30","unresolved":false,"context_lines":[{"line_number":49,"context_line":"* Adding an optional property to a resource representation which may be"},{"line_number":50,"context_line":"  supplied by clients, assuming the API previously would ignore this property."},{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_1e9b1919","line":52,"in_reply_to":"3a461143_d9269d67","updated":"2017-01-31 18:48:37.000000000","message":"In the discussion we\u0027ve had about this in the recent past the idea is that the projects, qa and api-wg to reach consensus and when they cannot the TC is adjudicator. That\u0027s a primary role of the TC that rarely gets used.\n\nWe can write this document to make that the clear path, if that\u0027s what we want.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_25c69249","line":57,"range":{"start_line":57,"start_character":23,"end_line":57,"end_character":33},"updated":"2017-01-26 22:58:23.000000000","message":"This should be explicit to include changes to property option/value mutation/removal as well as property names being bad here","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_85dd8616","line":58,"range":{"start_line":58,"start_character":2,"end_line":58,"end_character":24},"updated":"2017-01-26 22:58:23.000000000","message":"This needs to be much clearer with respect to intent and evaluation criteria.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"14e6ed3f0533042fb3f5ce675218e17e5ffb6f30","unresolved":false,"context_lines":[{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_1e1eb96f","line":58,"in_reply_to":"3a461143_85dd8616","updated":"2017-01-31 18:48:37.000000000","message":"The handling of resource representation in both request and response is difficult. We\u0027ve made it pretty clear elsewhere that request bodies which are not aligned with expectations should respond with a 400 to indicate that they are not \"correct\". That means that any change to the definition of correct is a boundary, which is fine, but for newish projects means there are going to be boundaries frequently (placement api is a good example).\n\nAnd the point is to not change often, right, if what we want is \"stability\"?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":17716,"name":"Luz Cazares","email":"luz.cazares@intel.com","username":"luzcazares"},"change_message_id":"03fa904c7d3ce6c086a9bfc61b29f6d6710157b6","unresolved":false,"context_lines":[{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_9731c75c","line":61,"range":{"start_line":54,"start_character":0,"end_line":61,"end_character":54},"updated":"2017-01-23 20:28:40.000000000","message":"Is there a guideline about acceptable deprecation processes?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"2368196c38165830f6aad1cc32680c1da289d166","unresolved":false,"context_lines":[{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_824e7594","line":61,"in_reply_to":"3a461143_21051810","updated":"2017-02-02 17:56:28.000000000","message":"We keep going around in circles on this. It\u0027s exacerbated by the fact that the discussion is happening in several venues too. \n\nShall we define stability and compatibility, with respect to the api wg guidelines, at the top of this document?\n\nThat would lay the ground work for the remainder of the document and give us a place to coalesce the discussion.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_7d4263af","line":61,"in_reply_to":"3a461143_824e7594","updated":"2017-02-08 22:59:16.000000000","message":"It also depends on whether you define \"stability\" as \"never ever ever ever changes\" or \"never surprises you\".\nDeprecation should be possible; abandonment should not. Besides warning that a change is coming, advice on how to handle that change is important, too.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"14e6ed3f0533042fb3f5ce675218e17e5ffb6f30","unresolved":false,"context_lines":[{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_21051810","line":61,"in_reply_to":"3a461143_8512e6b2","updated":"2017-01-31 18:48:37.000000000","message":"Yeah, if we are truly asserting stability, then nothing is ever deprecated. Is that what we want?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"ac47f34a78513cfc0ad0e7d5b14bca6724dba193","unresolved":false,"context_lines":[{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_8512e6b2","line":61,"range":{"start_line":54,"start_character":0,"end_line":61,"end_character":54},"in_reply_to":"5a3905b3_9731c75c","updated":"2017-01-26 22:58:23.000000000","message":"If this is just not acceptable, there is no acceptable deprecation is there?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"7e40d2eacdaca8cd5f770cef5a2358877d5e7679","unresolved":false,"context_lines":[{"line_number":51,"context_line":""},{"line_number":52,"context_line":"The following types of changes are generally **not** considered acceptable:"},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"* A change such that a request which was successful before now results in an"},{"line_number":55,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":56,"context_line":"  existing error condition)."},{"line_number":57,"context_line":"* Changing or removing a property in a resource representation."},{"line_number":58,"context_line":"* Changing the semantics of a property in a resource representation which"},{"line_number":59,"context_line":"  may be supplied by clients."},{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_0fb0298b","line":61,"range":{"start_line":54,"start_character":0,"end_line":61,"end_character":54},"in_reply_to":"5a3905b3_9731c75c","updated":"2017-01-25 13:33:23.000000000","message":"Yes, read this for details:\nhttps://governance.openstack.org/tc/reference/tags/assert_follows-standard-deprecation.html#requirements","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":60,"context_line":"* Changing or removing a response header."},{"line_number":61,"context_line":"* Changing which response code is returned on success."},{"line_number":62,"context_line":""},{"line_number":63,"context_line":"You may feel a particular case is special and warrants an incompatible API"},{"line_number":64,"context_line":"change. Please consider these responses to commonly used justifications:"},{"line_number":65,"context_line":""},{"line_number":66,"context_line":"*\"The change is needed to improve API consistency.\"*"},{"line_number":67,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_24cc34ba","line":64,"range":{"start_line":63,"start_character":0,"end_line":64,"end_character":72},"updated":"2017-02-01 07:42:20.000000000","message":"I like this part and it answers a lot of question :)","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5046,"name":"Lance Bragstad","email":"lbragstad@redhat.com","username":"ldbragst"},"change_message_id":"2a29297bb07c39bfab322d4321f88c8a9925d520","unresolved":false,"context_lines":[{"line_number":67,"context_line":""},{"line_number":68,"context_line":"Your desire to improve API consistency is appreciated, but all APIs have"},{"line_number":69,"context_line":"warts. Inconsistencies that need breaking changes can be fixed in a new API"},{"line_number":70,"context_line":"version. Please find a way to channel your efforts into preparations to fix"},{"line_number":71,"context_line":"these consistencies in the next API version."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_08c911ac","line":70,"updated":"2017-01-18 14:55:33.000000000","message":"Speaking of new API versions. Do we want to add a section on microversions and how that relates to this discussion? Or is that a little to implementation specific?","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":113,"name":"Jonathan Bryce","email":"jbryce@jbryce.com","username":"jbryce"},"change_message_id":"dbdb3ac36af70cce85ba32602a17818776745219","unresolved":false,"context_lines":[{"line_number":67,"context_line":""},{"line_number":68,"context_line":"Your desire to improve API consistency is appreciated, but all APIs have"},{"line_number":69,"context_line":"warts. Inconsistencies that need breaking changes can be fixed in a new API"},{"line_number":70,"context_line":"version. Please find a way to channel your efforts into preparations to fix"},{"line_number":71,"context_line":"these consistencies in the next API version."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a3c09a3_79997e78","line":70,"in_reply_to":"7a3c09a3_08c911ac","updated":"2017-01-18 17:42:11.000000000","message":"I know not everyone loves microversions, but it is a mechanism that is a big part of API compatibility for some of the most widely deployed APIs. I think having something that at least refers to the concept would be useful.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"965e2e705d70e350b8fdd538d08c6101e5dc68b9","unresolved":false,"context_lines":[{"line_number":67,"context_line":""},{"line_number":68,"context_line":"Your desire to improve API consistency is appreciated, but all APIs have"},{"line_number":69,"context_line":"warts. Inconsistencies that need breaking changes can be fixed in a new API"},{"line_number":70,"context_line":"version. Please find a way to channel your efforts into preparations to fix"},{"line_number":71,"context_line":"these consistencies in the next API version."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_0c4b5db1","line":70,"in_reply_to":"7a3c09a3_79997e78","updated":"2017-01-20 21:24:10.000000000","message":"Agreed. Versioning is central to any discussion around compatibility.\n\nThis paragraph assumes an OpenStack API is versioned. It should be made explicit.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"7e40d2eacdaca8cd5f770cef5a2358877d5e7679","unresolved":false,"context_lines":[{"line_number":80,"context_line":"certain behaviours, that may give us some small additional leeway when it"},{"line_number":81,"context_line":"comes to making changes."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_afcb951d","line":83,"updated":"2017-01-25 13:33:23.000000000","message":"Link to the doc guidelines http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html and then have a sentence such as,\n\n\"At a minimum the reference information must be documented using the standard tooling for all OpenStack projects.\"","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5314,"name":"Brian Rosmaita","email":"rosmaita.fossdev@gmail.com","username":"brian-rosmaita"},"change_message_id":"2ff6db2658b339eb32589a0d523d9a5700b1b668","unresolved":false,"context_lines":[{"line_number":81,"context_line":"comes to making changes."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":87,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_1ce813e2","line":84,"updated":"2017-01-26 21:32:38.000000000","message":"Here\u0027s another example:\n\nThe existing API is well documented but a different response code is returned by the API for a particular call.\n\nI don\u0027t know if this is the right place to discuss this, but this has happened with Glance (of course!).  Anyway, Ken told me to bring it up, so here we go.  I think this provides a good corner case, plus, I would like to know how this should be fixed in Ocata, so this is not merely theoretical.  There are two rival patches to fix this problem:\n\n(A) - change the API to return the correct response: https://review.openstack.org/#/c/420038/\n\n(B) - change the api-ref to reflect the current (incorrect) response: https://review.openstack.org/#/c/425487/\n\nThis is an interesting case because of the following:\n\n(1) All the delete-metadefs-* calls, as specifically stated in the documentation, return a 204 upon success.\n\n(2) The documentation specifically states that the delete-metadefs-tag call should return a 204 upon success.\n\n(3) The delete-metadefs-tag is returning a 200 with no response body upon success.\n\n(4) All the other delete-metadefs-* calls do in fact return a 204 with no response body upon success.\n\nNow it seems pretty obvious to me that this is a bug that should be fixed by (A).  But it seems equally obvious to Ken that we cannot change the response, we are stuck with 200 and must change the documentation.\n\nI\u0027m not going to argue about this here, you can go to patch (A) to see some detailed arguments.  I\u0027m bringing this up for two reasons:\n\n* This illustrates the need for a clear adjudication procedure.\n\n* If this isn\u0027t an allowable change, then I can\u0027t imagine what could be.  So let\u0027s dispense with the \"guidelines\" talk and just make these rules, and then the adjudication procedure is to simply follow the rules.  That will save everyone a lot of time.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5314,"name":"Brian Rosmaita","email":"rosmaita.fossdev@gmail.com","username":"brian-rosmaita"},"change_message_id":"57c2dc6904896a7ae8210a9b463ab0b6fd4386c8","unresolved":false,"context_lines":[{"line_number":81,"context_line":"comes to making changes."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":87,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_7f4ae9ad","line":84,"in_reply_to":"3a461143_1ce813e2","updated":"2017-01-26 21:52:26.000000000","message":"By the way, I encourage you to also look at patch (B): https://review.openstack.org/#/c/425487/ , because it illustrates why we need a clear adjudication procedure.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"caadaf423bc57843bd13ffdb4c2e856e179024af","unresolved":false,"context_lines":[{"line_number":81,"context_line":"comes to making changes."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":87,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_9354e921","line":84,"in_reply_to":"3a461143_7f4ae9ad","updated":"2017-01-27 01:42:43.000000000","message":"Thanks Brian,\n\nThe above is well written. One more thing is that the API has been published since Dec 18/2014, so we have many users on current status code. And my basic guideline is based on https://review.openstack.org/#/c/100335\n\n The canonical source for API behavior is the code *not* documentation.\n Documentation is manually generated after the code by folks looking at the\n code and writing up what they think it does, and it is very easy to get\n this wrong.\n\n This policy is in place to prevent us from making backwards incompatible\n changes to APIs.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5314,"name":"Brian Rosmaita","email":"rosmaita.fossdev@gmail.com","username":"brian-rosmaita"},"change_message_id":"02a75a174ca57609b51bcecd2821bef524d738c8","unresolved":false,"context_lines":[{"line_number":81,"context_line":"comes to making changes."},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":87,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_204bc4b1","line":84,"in_reply_to":"3a461143_9354e921","updated":"2017-01-27 15:26:19.000000000","message":"Thanks for the reference to https://review.openstack.org/#/c/100335 .  That\u0027s a nova policy, however, not an OpenStack-wide policy (yet).  Also, it pre-dates the \"specs\" movement and the api-ref in-tree documentation movement.  So I don\u0027t think that it\u0027s necessarily true any more to say that documentation is generated after the fact by people who are writing up what they think the code does.\n\nLook, I\u0027m not saying that the policy articulated in https://review.openstack.org/#/c/100335 is not a defensible point of view.  All I\u0027m saying is that it\u0027s not obviously applicable for (a) the general situation in 2017, and (b) the specific situation described above.  Thus the need for clarification for whether the stuff in this patch we are reviewing right here consists of (i) guidelines, or (ii) rules.\n\nFurther, as I mentioned on the other patch, even though users are consuming the current status code (obviously, because that\u0027s what we\u0027re returning), this doesn\u0027t mean that we are going to break those users by changing from the current 200 response to the documented 204 response.  What I mean is that a reasonable API consumer faced with the above situation (that is, items (1)-(4), specified in my previous comment) is *not* going to change their code to accept a 200, because it looks like an obvious bug.  Instead, they\u0027re going to code for a 2xx range response to indicate success until the bug gets fixed.\n\nBut that\u0027s neither here nor there.  The key point is that we need some clarity on what\u0027s going on here.  If it\u0027s never allowable to change from 200-\u003e204, even in this situation where it\u0027s an obvious bug, then let\u0027s say that in this document so that it\u0027s clear that this is not allowed.\n\nFurther, when we fix the bug but changing the documentation, not the code, we can point to this policy in the documentation.  Because clearly when we do change the documentation, we can\u0027t simply say this call returns a 200, because a user looking at the docs is going to wonder if it\u0027s a typo, given that all the other calls for this operation on metadefs, do, in fact return a 204 upon success.\n\nAgain, the reason I\u0027m pushing this isn\u0027t simply because I hate to lose an argument (though that\u0027s certainly part of it!), but because I think this is a useful case to consider.   As I said somewhere else, if this particular case isn\u0027t an exception, then I can\u0027t imagine what else could be.  And if that\u0027s the case, then let\u0027s stop talking about \"guidelines\" and change these into rules, and the situation will be much more clear.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"f4c9a28baa4c359712db8b7f5b9135218d1da39b","unresolved":false,"context_lines":[{"line_number":82,"context_line":""},{"line_number":83,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":86,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"},{"line_number":89,"context_line":"command line interfaces.\"*"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3a461143_c4d2905b","line":86,"range":{"start_line":85,"start_character":0,"end_line":86,"end_character":73},"updated":"2017-02-01 07:42:20.000000000","message":"yea, API contract is what code is saying not document because that is something used by users/apps/sdk etc","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":5196,"name":"Matthew Treinish","email":"mtreinish@kortar.org","username":"treinish"},"change_message_id":"c2d30ecca2d5d50fc82fbc68e8809b4d66492473","unresolved":false,"context_lines":[{"line_number":96,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":97,"context_line":""},{"line_number":98,"context_line":"The following examples represent a selection of appropriately implemented"},{"line_number":99,"context_line":"API changes based on the guidance provided in this document."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":"**Failing silently**"},{"line_number":102,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_d6787592","line":99,"updated":"2017-01-19 06:19:18.000000000","message":"I like having an examples section but maybe we could modernize some of these. Especially things like the references to the XML api.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"965e2e705d70e350b8fdd538d08c6101e5dc68b9","unresolved":false,"context_lines":[{"line_number":109,"context_line":"* Launchpad bug - `[novaclient] root-password fails and does not return"},{"line_number":110,"context_line":"  error \u003chttps://bugs.launchpad.net/nova/+bug/1038227\u003e`_"},{"line_number":111,"context_line":""},{"line_number":112,"context_line":"**Out of spec features belong in extensions**"},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"The ``config_drive`` attribute on servers is not part of the 1.1 Compute API"},{"line_number":115,"context_line":"spec, so it was moved into an extension which could be disabled."}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_2cef3988","line":112,"updated":"2017-01-20 21:24:10.000000000","message":"If we\u0027re pulling out extensions language, this needs to be removed along with a handful of things below.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"965e2e705d70e350b8fdd538d08c6101e5dc68b9","unresolved":false,"context_lines":[{"line_number":117,"context_line":"* Launchpad bug - `OSAPI v1.1 needs to document config-drive as an"},{"line_number":118,"context_line":"  extension \u003chttps://bugs.launchpad.net/nova/+bug/833331\u003e`_"},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"**Adding new header OK; changing response code not so much**"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"Rather than returning \"200 OK\" for successful volume creation, we should"},{"line_number":123,"context_line":"return \"201 Created\" and include a ``Location`` header. It was decided that"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_0c90bdeb","line":120,"updated":"2017-01-20 21:24:10.000000000","message":"The \"not so much\" is cutesy. I somehow doubt it translates well for non-native English speakers. It should just be \"is not\" or something appropriate.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":117,"context_line":"* Launchpad bug - `OSAPI v1.1 needs to document config-drive as an"},{"line_number":118,"context_line":"  extension \u003chttps://bugs.launchpad.net/nova/+bug/833331\u003e`_"},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"**Adding new header OK; changing response code not so much**"},{"line_number":121,"context_line":""},{"line_number":122,"context_line":"Rather than returning \"200 OK\" for successful volume creation, we should"},{"line_number":123,"context_line":"return \"201 Created\" and include a ``Location`` header. It was decided that"}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_bde4cbab","line":120,"in_reply_to":"5a3905b3_0c90bdeb","updated":"2017-02-08 22:59:16.000000000","message":"+1","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"a7dc6bc9c25d6ae5d7d0b91d92e35f0471cfd144","unresolved":false,"context_lines":[{"line_number":138,"context_line":""},{"line_number":139,"context_line":"Fixing incorrect counting of hosts in instance usage audit log."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"* Launchpad bug - `Instance usage audit log extension miscounts hosts"},{"line_number":142,"context_line":"  \u003chttps://bugs.launchpad.net/nova/+bug/1030106\u003e`_"},{"line_number":143,"context_line":""},{"line_number":144,"context_line":"**Extension aliases**"},{"line_number":145,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"1a430d35_9dae2f2c","line":142,"range":{"start_line":141,"start_character":0,"end_line":142,"end_character":50},"updated":"2017-02-08 22:59:16.000000000","message":"This isn\u0027t an API change. It\u0027s an internal bug whose fix didn\u0027t change the structure of any API response, just the content. It should be removed.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"965e2e705d70e350b8fdd538d08c6101e5dc68b9","unresolved":false,"context_lines":[{"line_number":158,"context_line":"* Gerrit review - `Allow nova to guess device if not passed to attach"},{"line_number":159,"context_line":"  \u003chttps://review.openstack.org/#/c/10908/\u003e`_"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"**Missing Property From XML Representation**"},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"* Launchpad bug - `hypervisor_hostname in extended server status doesn\u0027t"},{"line_number":164,"context_line":"  appear in xml \u003chttps://bugs.launchpad.net/nova/+bug/1039276\u003e`_"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_ec59b15b","line":161,"updated":"2017-01-20 21:24:10.000000000","message":"XML support was dropped so this can be removed.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ab0d5abb068c51dfe65c09fcc1752cbad0152835","unresolved":false,"context_lines":[{"line_number":158,"context_line":"* Gerrit review - `Allow nova to guess device if not passed to attach"},{"line_number":159,"context_line":"  \u003chttps://review.openstack.org/#/c/10908/\u003e`_"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"**Missing Property From XML Representation**"},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"* Launchpad bug - `hypervisor_hostname in extended server status doesn\u0027t"},{"line_number":164,"context_line":"  appear in xml \u003chttps://bugs.launchpad.net/nova/+bug/1039276\u003e`_"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5a3905b3_3971aa78","line":161,"in_reply_to":"5a3905b3_ec59b15b","updated":"2017-01-24 20:24:03.000000000","message":"Yeah, nice catch. XML support was terrible based on both Nova and Tempest experiences. So here should be removed.","commit_id":"3e0f2da44b3ec55ba33775ef11095a0bfc232b1a"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":63,"context_line":"          definition not adhering to the guidelines for compatibility and"},{"line_number":64,"context_line":"          stability. The project itself must make the decisions on how to"},{"line_number":65,"context_line":"          evolve their API. If this leads to conflicts with other projects"},{"line_number":66,"context_line":"          within the OpenStack ecosystem the role of the API-WG is solely"},{"line_number":67,"context_line":"          to help clarify the guidelines and provide advice on how to"},{"line_number":68,"context_line":"          minimize the impact of changes. The Technical Committee is the"},{"line_number":69,"context_line":"          body which provides adjudication and mediation when consensus"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_535b672e","line":66,"range":{"start_line":66,"start_character":31,"end_line":66,"end_character":40},"updated":"2017-02-22 05:26:34.000000000","message":"a comma after \"ecosystem\" would improve the readability of this sentence.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":63,"context_line":"          definition not adhering to the guidelines for compatibility and"},{"line_number":64,"context_line":"          stability. The project itself must make the decisions on how to"},{"line_number":65,"context_line":"          evolve their API. If this leads to conflicts with other projects"},{"line_number":66,"context_line":"          within the OpenStack ecosystem the role of the API-WG is solely"},{"line_number":67,"context_line":"          to help clarify the guidelines and provide advice on how to"},{"line_number":68,"context_line":"          minimize the impact of changes. The Technical Committee is the"},{"line_number":69,"context_line":"          body which provides adjudication and mediation when consensus"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_066776e9","line":66,"in_reply_to":"da36d5c6_535b672e","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"d1bed8230874032934f2dfb34027a47d60c9f74e","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"1a430d35_de0884dc","line":115,"range":{"start_line":115,"start_character":2,"end_line":115,"end_character":47},"updated":"2017-02-09 19:19:26.000000000","message":"should include any response in the 200-499 range, not just client errors","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"f800be13c92c524214fdaa78b97d42ad47cf763b","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_6a46f7c0","line":115,"in_reply_to":"1a430d35_99ee16b3","updated":"2017-02-09 23:39:48.000000000","message":"I can imagine unnecessarily restrictive input validation (harkening back to discussions of guidelines on interpreting truthiness: TRUE|True|true|T|t|...) could result in a 500 where a 200 or 201 or such would result from a change which could be non-breaking.\n\nIf others feel differently, I\u0027d appreciate the perspective.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_26ad5a88","line":115,"in_reply_to":"1a430d35_de0884dc","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"36aad20eed0e1248f9add2da85cd20e9152bd92a","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"1a430d35_99ee16b3","line":115,"in_reply_to":"1a430d35_de0884dc","updated":"2017-02-09 19:43:52.000000000","message":"I had made the perhaps wrong assumption that anything that resulted in a 500 was the result of something being erroneous in the first place. I can change this but I\u0027d like to see a bit more discussion on what we think the flow is here.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_dc72edac","line":115,"in_reply_to":"fa31d9ce_07bd90d7","updated":"2017-02-22 05:26:34.000000000","message":"Right... it\u0027s quite possible that the server would fail to properly process some subset of valid requests that was not anticipated by the implementation. The fix would be 5xx -\u003e 2xx.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":114,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":115,"context_line":"  informative error response in the ``400-499`` range."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_07bd90d7","line":115,"in_reply_to":"fa31d9ce_6a46f7c0","updated":"2017-02-15 17:26:56.000000000","message":"A 5xx just means that something was wrong on the server side of things. It doesn\u0027t mean that anything was necessarily wrong with the request. So a 5xx -\u003e 200 is acceptable, too.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":7350,"name":"Jordan Pittier","email":"jordan.pittier@gmail.com","username":"JordanP"},"change_message_id":"965feb952608cf2d6b98cbebfe9b1f2b31e86120","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_bfb8c4e6","line":119,"updated":"2017-02-13 14:14:31.000000000","message":"I am new to the versioning best practices, but new url should be unknown to old clients, so unused by old clients, so no risk to break them right ?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_98e457ad","line":119,"in_reply_to":"fa31d9ce_40c9075a","updated":"2017-02-16 14:21:26.000000000","message":"I agree that if I\u0027ve selected a version I should expect all of the API actions for that version to work.\n\nI agree about policy, but want to say a thing slightly more strongly:\n\nThe way we are treating policy denials is the absolute worst thing about OpenStack and is the biggest mistake we\u0027ve made.\n\nThe API is the API. Period. It\u0027s public, it\u0027s documented and it\u0027s well known. If I am denied by policy I need to get a 401 or 403 not a 404.\n\nDiscovery is great for things like \"what versions are available\" \"what services are available\" and hopefully sometime in the future \"what deployment decisions have been made - e.g. this cloud accepts qcow2 images or this cloud requires floating ips\" - since those are not tied to API versions but rather to choices made in the deployment.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"19f96607c3bc6f926f29cfb55d584511180934c7","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_7b3b1d39","line":119,"in_reply_to":"fa31d9ce_40c9075a","updated":"2017-02-16 15:09:28.000000000","message":"I don\u0027t know.\n\nDefCore accepted the discoverability solution in the noted spec. Compatibility would seem to be in their purview. Discoverability also provides clear way to explain 401 and 403 behaviors without having to carve an exception (for better or worse).\n\nTo be very clear, I don\u0027t think I can reasonably claim discoverability as a given. I suggest that it \"should\" rather than \"is\" or \"must be,\" and am giving the best reasoning I can think of, so that we can be thorough in review. My positioning here is driven by a desire for coming to a clean and considered conclusion rather than offering a personal position. I realize on rereading that might not have been clear enough.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"e78ebe4bf8f7b69530940df71b1f2a693f43c936","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_40c9075a","line":119,"in_reply_to":"fa31d9ce_54f56dea","updated":"2017-02-16 13:16:00.000000000","message":"\u003e Discoverability should be an accepted mechanism for dealing with this.\n\nShould it? I\u0027ve been reading the discussions associated with this topic to mean that a single curl statement used on cloud A should work on cloud B and I _should not_ have to make different curl statements based on the results of discovery. Discovery is the process by which I determine what versions are available, however if I\u0027ve already chosen a version, I can just use it and expect it to work if:\n\n* that version is supported at the target cloud\n* I\u0027m not denied by policy\n\nThat latter point is important and should perhaps be made more clear in this document: authentication and authorization handling is cloud specific and 401 and 403 can always be expected (alongside whatever the codes for success are) because of that.\n\n(That \"Should it?\" above is _not_ rhetorical. I honestly don\u0027t know what people think should happen here.)","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_46440eb6","line":119,"in_reply_to":"fa31d9ce_7b3b1d39","updated":"2017-03-03 20:33:30.000000000","message":"We decided at ptg that adding a url does require a version.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"36af389753c5364c62deee2ecc6fb5c990091133","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_c1b5f631","line":119,"in_reply_to":"fa31d9ce_98e457ad","updated":"2017-02-16 15:09:06.000000000","message":"Add ing a URL is a structural change to an API and must be signaled in a version bump.  Adding an acceptable value is a content change, and as a API consumer I\u0027d like to also see that signaled, but can live with a discovery mechanism, although in a CLI world keeping the round trips down is a big plus.\n\nDiscovery is not a panacea that we can lean on for everything that is inconvenient.  The current discovery discussion seems to be shaping up for some number \u003eN where N may be greater than the number of fingers on my left hand.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"8c1d5a6e52e7c14f4044e8b4ed28d3f61960a1bd","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_4102e670","line":119,"in_reply_to":"fa31d9ce_98e457ad","updated":"2017-02-16 15:16:31.000000000","message":"I feel like if discovery was the right answer for all of this, the APIs should not be REST apis, they should be WSDL where the discovery tooling all exists.\n\nOne of the reasons for them being REST apis is the fact that they are targeted at humans, and as such do not assume they are generic conduits where you need to make API calls to understand how to make API calls in the first place.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2ba41163766656a55abfbd33bee883f50be30363","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_b07c23b6","line":119,"in_reply_to":"fa31d9ce_9e0cb4ee","updated":"2017-02-15 01:23:48.000000000","message":"But for interop, version change is much needed as long as we argue on some other discovery capabilities mechanism.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_b2f6c48c","line":119,"in_reply_to":"fa31d9ce_b07c23b6","updated":"2017-02-15 17:26:56.000000000","message":"Interop requires that the same request for the same version will always return the same response, no matter what cloud is handling that request. So if a new URL returns a 200 OK from one cloud at version N, and returns 404 from another cloud also at version N, that\u0027s a problem.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"09f5d9e2baf3aaea9f1ff8bb142089eccda07e8d","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_54f56dea","line":119,"in_reply_to":"fa31d9ce_b2f6c48c","updated":"2017-02-15 21:08:05.000000000","message":"This is a \"too-simple\" an interpretation. Discoverability should be an accepted mechanism for dealing with this.\n\n* Policy differences create a situation where one cloud returns 200 and another cloud returns 403 on the same endpoint. This isn\u0027t a compatibility failure (particularly if the difference is discoverable). The above is a too-simple interpretation of compatibility. We are busy accounting for this concern right now in the capabilities discovery guideline [1].\n\n* The Glance Image Import [2] spec specifically allows for something /like/ this in clouds which are considered compatible by the DefCore team. This is specifically because of discoverability.\n\n[1] Ib4e2d216f7a606b1e1626fbe79cda11ad0a06c07\n\n[2] http://specs.openstack.org/openstack/glance-specs/specs/mitaka/approved/image-import/image-import-refactor.html","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"11452d28e6c2fb95891b37ca4b08a966588bc22f","unresolved":false,"context_lines":[{"line_number":116,"context_line":""},{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_9e0cb4ee","line":119,"in_reply_to":"fa31d9ce_bfb8c4e6","updated":"2017-02-14 11:25:04.000000000","message":"Yeah, I guess you\u0027re right. Perhaps there needs to be a section which enumerates changes which are backwards compatible but ought to be indicated by a version change anyway, to align with the opt-in for new features concept above?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_dcce6db3","line":120,"range":{"start_line":120,"start_character":34,"end_line":120,"end_character":43},"updated":"2017-02-22 05:26:34.000000000","message":"if adding a new URL requires a version change, then shouldn\u0027t adding a new request header require a version change as well, for the same reasons, regardless of whether that new header is required?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":117,"context_line":"The following changes **do** require a version change:"},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_06da16e8","line":120,"in_reply_to":"da36d5c6_dcce6db3","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":7350,"name":"Jordan Pittier","email":"jordan.pittier@gmail.com","username":"JordanP"},"change_message_id":"965feb952608cf2d6b98cbebfe9b1f2b31e86120","unresolved":false,"context_lines":[{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_3f1db4bd","line":121,"updated":"2017-02-13 14:14:31.000000000","message":"I am not a native english speaker so I am not sure I fully understand the \"which signals client processing behavior\" part.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_068856c4","line":121,"in_reply_to":"fa31d9ce_07b910cc","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"11452d28e6c2fb95891b37ca4b08a966588bc22f","unresolved":false,"context_lines":[{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_be241860","line":121,"in_reply_to":"fa31d9ce_3f1db4bd","updated":"2017-02-14 11:25:04.000000000","message":"I was trying to indicate that something like changing the \u0027content-type\u0027 header has a much different impact than changing the \u0027server\u0027 or \u0027date\u0027 header. In the next version I\u0027ll try to be more clear about that.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* Adding a new URL."},{"line_number":120,"context_line":"* Adding a new response header or requiring a new request header."},{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_07b910cc","line":121,"in_reply_to":"fa31d9ce_be241860","updated":"2017-02-15 17:26:56.000000000","message":"How about: \"Changing the value of a response header which would change how the response should be processed by the client\"","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":7350,"name":"Jordan Pittier","email":"jordan.pittier@gmail.com","username":"JordanP"},"change_message_id":"965feb952608cf2d6b98cbebfe9b1f2b31e86120","unresolved":false,"context_lines":[{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"},{"line_number":125,"context_line":"  either a request or a response."},{"line_number":126,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":127,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_9f830004","line":124,"updated":"2017-02-13 14:14:31.000000000","message":"typo: resource resource ?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":121,"context_line":"* Changing the value of a response header which signals client processing"},{"line_number":122,"context_line":"  behavior. For example changing the value of the ``Content-Type`` header"},{"line_number":123,"context_line":"  to add a new media-type."},{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"},{"line_number":125,"context_line":"  either a request or a response."},{"line_number":126,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":127,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_c6b8fe77","line":124,"in_reply_to":"fa31d9ce_9f830004","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2ba41163766656a55abfbd33bee883f50be30363","unresolved":false,"context_lines":[{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"},{"line_number":125,"context_line":"  either a request or a response."},{"line_number":126,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":127,"context_line":"  representation (request or response)."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":"The following changes are possible if a version change is made but are"},{"line_number":130,"context_line":"considered poor form:"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_e2fc0eba","line":127,"range":{"start_line":127,"start_character":37,"end_line":127,"end_character":39},"updated":"2017-02-15 01:23:48.000000000","message":"how about adding below also in this section\n- Changing which response code is returned on success.\n- removing a response header.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"8e4263906a4c8dfe0620968ac05a87ec8f5d1834","unresolved":false,"context_lines":[{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"},{"line_number":125,"context_line":"  either a request or a response."},{"line_number":126,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":127,"context_line":"  representation (request or response)."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":"The following changes are possible if a version change is made but are"},{"line_number":130,"context_line":"considered poor form:"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_58b6408b","line":127,"range":{"start_line":127,"start_character":37,"end_line":127,"end_character":39},"in_reply_to":"fa31d9ce_d29258f5","updated":"2017-02-20 18:31:29.000000000","message":"Yea it is covered in that but having that separably is nice to understand clearly.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":124,"context_line":"* Adding or removing a property in a resource resource representation in"},{"line_number":125,"context_line":"  either a request or a response."},{"line_number":126,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":127,"context_line":"  representation (request or response)."},{"line_number":128,"context_line":""},{"line_number":129,"context_line":"The following changes are possible if a version change is made but are"},{"line_number":130,"context_line":"considered poor form:"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_d29258f5","line":127,"range":{"start_line":127,"start_character":37,"end_line":127,"end_character":39},"in_reply_to":"fa31d9ce_e2fc0eba","updated":"2017-02-15 17:26:56.000000000","message":"The success response code is just like any other response code change. I don\u0027t think it needs a special mention. And probably instead of just saying \"remove response header\", how about \"adding, removing, or modifying any response header\"?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":133,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":134,"context_line":"  existing error condition)."},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"* Removing a URL."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"Unresolved Questions"},{"line_number":139,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_f8bf135e","line":136,"updated":"2017-02-16 14:21:26.000000000","message":"I\u0027d really prefer we did not write in a document that removing a URL is ok, even if it\u0027s couched in \u0027considered poor form\u0027\n\nRemoving stuff will at some point in life require the logic switching to fall on the shoulders of an end user.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"9977d0bee3c52cf80cf19b826c48ea0ffb5bf75b","unresolved":false,"context_lines":[{"line_number":133,"context_line":"  error response (unless the success reported previously was hiding an"},{"line_number":134,"context_line":"  existing error condition)."},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"* Removing a URL."},{"line_number":137,"context_line":""},{"line_number":138,"context_line":"Unresolved Questions"},{"line_number":139,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_5ec3a78a","line":136,"in_reply_to":"fa31d9ce_f8bf135e","updated":"2017-02-16 14:49:39.000000000","message":"So Nova should keep the /images interface forever? I think there are definitely times where interfaces are bad enough that we need a way to get rid of them.\n\nI think it\u0027s fine to say \"really don\u0027t try to do this\", but leave the exception space there.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"d1bed8230874032934f2dfb34027a47d60c9f74e","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"1a430d35_9e735c15","line":148,"updated":"2017-02-09 19:19:26.000000000","message":"This text should probably answer the question of whether changes strictly expanding the property values does signal a version boundary, first.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"36aad20eed0e1248f9add2da85cd20e9152bd92a","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"1a430d35_f981dac4","line":148,"in_reply_to":"1a430d35_9e735c15","updated":"2017-02-09 19:43:52.000000000","message":"Isn\u0027t that what this says?\n\nIn case it\u0027s not clear I think we should resolve these \"unresolved questions\" before we publish this document, so anything in this section needs to be figured out and once it is, moved somewhere above.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"f800be13c92c524214fdaa78b97d42ad47cf763b","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_4ddb0d1c","line":148,"in_reply_to":"1a430d35_f981dac4","updated":"2017-02-09 23:39:48.000000000","message":"I see the removal of \"foo\" as it\u0027s own question distinct from the introduction of \"zoom\".  Adding \"zoom\" wouldn\u0027t be something I would suggest requires a version bump. Removal of \"foo\" would.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"449132232f688231432d4508b246f30ffb77ec18","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_f2b50331","line":148,"in_reply_to":"fa31d9ce_1fc63048","updated":"2017-02-13 18:25:00.000000000","message":"Yeah, I also agree with Steve here.\nThe addition is backwards compatible, and the removal is backwards incompatible. It should be very different to handle these changes from the first purpose of line 11+.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_a9fd9d6f","line":148,"in_reply_to":"fa31d9ce_4c382b3e","updated":"2017-03-03 20:33:30.000000000","message":"moved a version of this into the \"needs a version change\" section","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":7350,"name":"Jordan Pittier","email":"jordan.pittier@gmail.com","username":"JordanP"},"change_message_id":"965feb952608cf2d6b98cbebfe9b1f2b31e86120","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_1fc63048","line":148,"in_reply_to":"fa31d9ce_4ddb0d1c","updated":"2017-02-13 14:14:31.000000000","message":"I agree with Steve: additions and removals are very different imo.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"52cb5e4bbce3a3f2cda372026de60ca2225e10d6","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_cc028d72","line":148,"in_reply_to":"fa31d9ce_61536a6d","updated":"2017-02-16 15:31:00.000000000","message":"I just realized a critical bit that is missing here, there are (at least) two kinds of enumerated values in our APIs: those that are expressed in code (resource state, active, error, etc) and those expressed in config.  I think the ones in code must be API versioned for all the reasons stated already, it\u0027s the ones in config (eg, image type) that are problematic and must be discovered.  We can\u0027t really version an API on a config value.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"937939a2378237dffda7b1bbd543b5278e3cbb17","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_4c677dea","line":148,"in_reply_to":"fa31d9ce_61536a6d","updated":"2017-02-16 15:28:20.000000000","message":"Just noting that I consider this to be resolved now, in favor of the needs of compatibility.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"971afe9b98fac230effdd2228775bbf75b7ca0a6","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_4c382b3e","line":148,"in_reply_to":"fa31d9ce_61536a6d","updated":"2017-02-17 16:59:01.000000000","message":"My summary of this: https://blog.leafe.com/interop-api-requirements/","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_b275e4cb","line":148,"in_reply_to":"fa31d9ce_82c0b251","updated":"2017-02-15 17:26:56.000000000","message":"Interop concerns dictate that any behavior change requires a new version. While additions and removals are very different, both will break the behavior consistency necessary for interop.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"36af389753c5364c62deee2ecc6fb5c990091133","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_fed61b26","line":148,"in_reply_to":"fa31d9ce_9880d78d","updated":"2017-02-16 15:09:06.000000000","message":"Agree on an indication of some sort for the client to find out if/when the new value is acceptable.  As someone once said, \"versions are cheap\".\n\nBut see my point above regarding discovery, it\u0027s not a cure-all here.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"8c1d5a6e52e7c14f4044e8b4ed28d3f61960a1bd","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_61536a6d","line":148,"in_reply_to":"fa31d9ce_9880d78d","updated":"2017-02-16 15:16:31.000000000","message":"If there was only ever one version of openstack out there, and it always moved forward in time, adding a new field is fine.\n\nBut if you don\u0027t require signaling for new fields, you end up with.\n\nVersion 3.4 of /foo on provider X supports {foo, bar, baz}, but Version 3.4 of /foo on provider Y supports {foo, bar}  (baz was added without a version bump).\n\nThat\u0027s exactly one of the things we are trying to avoid with API stability and compatibility.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_9880d78d","line":148,"in_reply_to":"fa31d9ce_b275e4cb","updated":"2017-02-16 14:21:26.000000000","message":"Buming the version for the new value is a good idea. Removing support for the old value is always bad, regardless of whether a version bumped or not.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"11452d28e6c2fb95891b37ca4b08a966588bc22f","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_fed05021","line":148,"in_reply_to":"fa31d9ce_f2b50331","updated":"2017-02-14 11:25:04.000000000","message":"Good points. See my comments above about using versioning to opt in to new behaviors. Is this addition issue something that would fit with that or do we think it is safe to just leave it out?","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2ba41163766656a55abfbd33bee883f50be30363","unresolved":false,"context_lines":[{"line_number":145,"context_line":"  maintaining its type."},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"  For example if a property once accepted \"foo\", \"bar\", or \"baz\" but then"},{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_82c0b251","line":148,"in_reply_to":"fa31d9ce_fed05021","updated":"2017-02-15 01:23:48.000000000","message":"I feel we should make removal of accepted values should go under version change.\n\nAlso for adding new values in allowed set without version can cause interop issue and should be with version change.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"f800be13c92c524214fdaa78b97d42ad47cf763b","unresolved":false,"context_lines":[{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"  It is relatively clear that it should if the change is from one of those"},{"line_number":154,"context_line":"  to ``202`` (where further work is required to establish the final result"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_10ce8c83","line":151,"updated":"2017-02-09 23:39:48.000000000","message":"If a project explicitly defines loose boundaries for response codes via documentation introduced in the same release as the implementation, then I believe that should be the binding constraint for that version.\n\nWithout that documentation, explicit behaviors should be the constraint for that version.\n\nExample 1: with initial documentation stating \"for endpoint /thingy/{thingy-id} expected response codes for PUT requests include 200, 201, 202 for success and 400, 401, 403 for errors. If a 202 is returned then see [other section] for checking the status of the operation\" then fluid response code behavior should be expected. It seems clear that an update to an existing resource should accept 200 or 202 as success, regardless of whether or not the initial implementation ever returned 202. In this case it would seem that an updated implementation to sometimes return a 202 respects both consistency and stability.\n\nThis still seems like an extremely conservative stance to me, but allows for forward thinking project teams to leave themselves valuable flexibility.\n\nI\u0027d also like to discuss carving out specific error response codes which should always be assumed as legitimate, even if insufficiently documented. This includes 401, 403, and 429 and possibly others. The 403 response could reflect deployer differences in policy. The last applies to the deployer concern of request throttling. Neither should be considered a violation of compatibility of the API.\n\nI\u0027ll leave some of the other edge cases untouched for the moment to see other feedback.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2ba41163766656a55abfbd33bee883f50be30363","unresolved":false,"context_lines":[{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"  It is relatively clear that it should if the change is from one of those"},{"line_number":154,"context_line":"  to ``202`` (where further work is required to establish the final result"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_6292de4d","line":151,"in_reply_to":"fa31d9ce_10ce8c83","updated":"2017-02-15 01:23:48.000000000","message":"I think code behaviour is something users care and use than doc. Doc always have bugs and cannot be API contract from starting. If they are then doc should not be changed at all in any cases but this is not case.\n\nMy vote is this is strict case of breaking users and must be done with version bump.\n\nsuccess code of API is external interface and user can use with exact match like \u003d\u003d200 or range checks like \"in 2xx range\". So we should not ignore \u003d\u003d200 cases. Because we no where says to user that not to use exact match \u003d\u003d200","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"09f5d9e2baf3aaea9f1ff8bb142089eccda07e8d","unresolved":false,"context_lines":[{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"  It is relatively clear that it should if the change is from one of those"},{"line_number":154,"context_line":"  to ``202`` (where further work is required to establish the final result"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_3c1ac917","line":151,"in_reply_to":"fa31d9ce_6292de4d","updated":"2017-02-15 21:08:05.000000000","message":"\u003e we no where says to user that not to use exact match \u003d\u003d200\n\nIncorrect. The situation I proposed says to \"not use exact match \u003d\u003d200\" **. See above.\n\nAt this point all new endpoints are being discovered through documentation ***, so API consumption has to start there. This is why it makes sense to respect docs as guidance for successful status codes at the time of endpoint introduction.\n\n** This is a proposal for a very specific carve-out which I have not seen precedent for, this isn\u0027t a cloaked reference to any current or past debates related to changing a status code on an existing endpoint.\n\n*** We have no discovery guideline accepted and the guideline in review still only provides an augment to documentation, not a complete replacement.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"fb04169013b2cc72d909f8240be2008028936afa","unresolved":false,"context_lines":[{"line_number":148,"context_line":"  \"zoom\" was added and \"foo\" removed, does that require a version?"},{"line_number":149,"context_line":""},{"line_number":150,"context_line":"* When changing the response code for a successful request does a change"},{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"  It is relatively clear that it should if the change is from one of those"},{"line_number":154,"context_line":"  to ``202`` (where further work is required to establish the final result"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_f252fc33","line":151,"in_reply_to":"fa31d9ce_6292de4d","updated":"2017-02-15 17:26:56.000000000","message":"Docs can be changed freely, as long as the new doc is a better reflection of reality. Changing the behavior of an API will always require a new version, even if it makes no sense to check for a specific 2xx code.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":151,"context_line":"  from ``200`` to ``204`` or ``201`` warrant a version?"},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"  It is relatively clear that it should if the change is from one of those"},{"line_number":154,"context_line":"  to ``202`` (where further work is required to establish the final result"},{"line_number":155,"context_line":"  of the request)."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Examples"},{"line_number":158,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_7c890126","line":155,"range":{"start_line":154,"start_character":13,"end_line":155,"end_character":17},"updated":"2017-02-22 05:26:34.000000000","message":"I think you\u0027re assuming that work is new. If that work already had to happen before, while the API was returning something other than 202 (obviously incorrectly), i.e. it was ONLY the response code that changed, then I don\u0027t think it\u0027s so clear.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":165,"context_line":"Your desire to improve API consistency is appreciated and desired, but all"},{"line_number":166,"context_line":"APIs have warts. Inconsistencies that need breaking changes can be fixed in"},{"line_number":167,"context_line":"a new API version. Please find a way to channel your efforts into"},{"line_number":168,"context_line":"preparations to fix these consistencies in the next API version."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"},{"line_number":171,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_38160b56","line":168,"updated":"2017-02-16 14:21:26.000000000","message":"Or just don\u0027t fix it. People have already written code to the old api. Add a new thing, but leave the old one.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":165,"context_line":"Your desire to improve API consistency is appreciated and desired, but all"},{"line_number":166,"context_line":"APIs have warts. Inconsistencies that need breaking changes can be fixed in"},{"line_number":167,"context_line":"a new API version. Please find a way to channel your efforts into"},{"line_number":168,"context_line":"preparations to fix these consistencies in the next API version."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"},{"line_number":171,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_3476603e","line":168,"in_reply_to":"da36d5c6_5ce27da0","updated":"2017-03-03 20:33:30.000000000","message":"I\u0027ve tried to include a bit of \"don\u0027t change it\" with \"consider all your options\".","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"36af389753c5364c62deee2ecc6fb5c990091133","unresolved":false,"context_lines":[{"line_number":165,"context_line":"Your desire to improve API consistency is appreciated and desired, but all"},{"line_number":166,"context_line":"APIs have warts. Inconsistencies that need breaking changes can be fixed in"},{"line_number":167,"context_line":"a new API version. Please find a way to channel your efforts into"},{"line_number":168,"context_line":"preparations to fix these consistencies in the next API version."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"},{"line_number":171,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_81c05e7e","line":168,"in_reply_to":"fa31d9ce_38160b56","updated":"2017-02-16 15:09:06.000000000","message":"++\n\nAs much as I hated using the Win32 API, they handled compatibility in a totally tolerable way.  Rather than changing an existing API Foo() as things evolved, they just added Foo2() or FooWithBar() or whatever.  Hits both needs even if it looks a bit ugly to us purists.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"2491ac839462daf7172d7dfe07c600980554f9ac","unresolved":false,"context_lines":[{"line_number":165,"context_line":"Your desire to improve API consistency is appreciated and desired, but all"},{"line_number":166,"context_line":"APIs have warts. Inconsistencies that need breaking changes can be fixed in"},{"line_number":167,"context_line":"a new API version. Please find a way to channel your efforts into"},{"line_number":168,"context_line":"preparations to fix these consistencies in the next API version."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":"*\"It is unlikely that any existing users of the API would be affected.\"*"},{"line_number":171,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"da36d5c6_5ce27da0","line":168,"in_reply_to":"fa31d9ce_81c05e7e","updated":"2017-02-22 05:26:34.000000000","message":"I have to disagree about leaving the old inconsistent API forever. Adding a new thing but never trimming out old things leads to APIs growing to a size that is not only hard to maintain (which has its own costs for users in dev time not spent on other things they want more) but overly complex for users. E.g. hard for users to sift through to find what they\u0027re looking for. Leave the old way for a while, sure, but not forever. Deprecation and eventual removal helps users (other than clients trying to support all possible environments, i.e. most users) as much or more than it helps dev maintainers. And keep in mind that those clients that are trying to support all environments can often find ways of doing that without something having to always work the way it used to. E.g. I used to have to write code that would check something seemingly unrelated to determine whether this response I got meant x or y, knowing that that seeminly unrelated thing worked differently back when this response meant x than it did when this response meant y. These kinds of hacks are ugly but they are par for the course when you\u0027re trying to do something heroic like support ANYTHING.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":171,"context_line":""},{"line_number":172,"context_line":"It is difficult to predict how people are using the APIs. Developers do the"},{"line_number":173,"context_line":"strangest things. As our APIs become more adopted over time, it will only"},{"line_number":174,"context_line":"become more futile to attempt to make such predictions."},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_bb19157c","line":174,"updated":"2017-02-16 14:21:26.000000000","message":"++\n\nThe one exception to this is \"nobody could have been counting on this because it actually physically did not work, so while fixing it will change the API behavior, it\u0027s not possible that anyone was depending on it since the broken thing was actually non-functional\"","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":171,"context_line":""},{"line_number":172,"context_line":"It is difficult to predict how people are using the APIs. Developers do the"},{"line_number":173,"context_line":"strangest things. As our APIs become more adopted over time, it will only"},{"line_number":174,"context_line":"become more futile to attempt to make such predictions."},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_34c82074","line":174,"in_reply_to":"fa31d9ce_bb19157c","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"aa871b6ae5d1eff88c2692dbef62f61cc711afe3","unresolved":false,"context_lines":[{"line_number":175,"context_line":""},{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":179,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_90db35ed","line":178,"updated":"2017-02-10 15:39:51.000000000","message":"Please link to the guidelines here.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":175,"context_line":""},{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":179,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_74f1b86a","line":178,"in_reply_to":"fa31d9ce_1e95243e","updated":"2017-03-03 20:33:30.000000000","message":"Done","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"11452d28e6c2fb95891b37ca4b08a966588bc22f","unresolved":false,"context_lines":[{"line_number":175,"context_line":""},{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":179,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_1e95243e","line":178,"in_reply_to":"fa31d9ce_90db35ed","updated":"2017-02-14 11:25:04.000000000","message":"Thanks, will do in a forthcoming version.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2,"name":"Monty Taylor","email":"mordred@inaugust.com","username":"mordred"},"change_message_id":"e531e58101f1a95b989409a7a94c6e333581a836","unresolved":false,"context_lines":[{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":179,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"},{"line_number":182,"context_line":"command line interfaces.\"*"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_5b401936","line":179,"updated":"2017-02-16 14:21:26.000000000","message":"API consumers may even know how the API works better. :)","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"8c1d5a6e52e7c14f4044e8b4ed28d3f61960a1bd","unresolved":false,"context_lines":[{"line_number":176,"context_line":"*\"The existing API is not well documented.\"*"},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"If an API\u0027s behavior isn\u0027t adequately documented, then developers using"},{"line_number":179,"context_line":"the API have no choice but to go by what they observe the behavior to be."},{"line_number":180,"context_line":""},{"line_number":181,"context_line":"*\"The change does not impact users of OpenStack\u0027s client libraries or"},{"line_number":182,"context_line":"command line interfaces.\"*"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_c1e1769c","line":179,"in_reply_to":"fa31d9ce_5b401936","updated":"2017-02-16 15:16:31.000000000","message":"++","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"2ba41163766656a55abfbd33bee883f50be30363","unresolved":false,"context_lines":[{"line_number":183,"context_line":""},{"line_number":184,"context_line":"We encourage developers to develop against OpenStack REST API. There will"},{"line_number":185,"context_line":"be many tools and applications which favor the REST API over our libraries"},{"line_number":186,"context_line":"or command line interfaces."},{"line_number":187,"context_line":""},{"line_number":188,"context_line":"References"},{"line_number":189,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"fa31d9ce_22c4663e","line":186,"range":{"start_line":186,"start_character":26,"end_line":186,"end_character":27},"updated":"2017-02-15 01:23:48.000000000","message":"can we have example cases like in PS1, those can be helpful to understand guidelines more clearly.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6afdb05a9cbe7ec012cdef9dfc0e850bece2dab4","unresolved":false,"context_lines":[{"line_number":183,"context_line":""},{"line_number":184,"context_line":"We encourage developers to develop against OpenStack REST API. There will"},{"line_number":185,"context_line":"be many tools and applications which favor the REST API over our libraries"},{"line_number":186,"context_line":"or command line interfaces."},{"line_number":187,"context_line":""},{"line_number":188,"context_line":"References"},{"line_number":189,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba2be162_74bff860","line":186,"in_reply_to":"fa31d9ce_22c4663e","updated":"2017-03-03 20:33:30.000000000","message":"If we still want examples after we get through this process, we can add them in a follow up. For the time being I\u0027d like to get the text of the guidance as robust as possible.","commit_id":"beed74095abf817a50ce542787ceca851ce7fb9e"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":44,"context_line":""},{"line_number":45,"context_line":"The gist here is that any service with a published API that also needs to"},{"line_number":46,"context_line":"make changes to that API (to fix or evolve it) needs to have a mechanism"},{"line_number":47,"context_line":"for versioning. This document does not address versioning, but a common"},{"line_number":48,"context_line":"mechanism used in OpenStack is described in"},{"line_number":49,"context_line":":doc:`microversion_specification`."},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":52,"context_line":"follow if it wishes to ensure API compatibility and stability."}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_d640a109","line":49,"range":{"start_line":47,"start_character":16,"end_line":49,"end_character":34},"updated":"2017-03-03 23:27:30.000000000","message":"One of the conclusions from the PTG was that no one could think of a way to implement this guideline with anything other than microversions. So instead of \u0027a common mechanism\u0027 maybe say \u0027the only approach that all agree will work\u0027.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":46,"context_line":"make changes to that API (to fix or evolve it) needs to have a mechanism"},{"line_number":47,"context_line":"for versioning. This document does not address versioning, but a common"},{"line_number":48,"context_line":"mechanism used in OpenStack is described in"},{"line_number":49,"context_line":":doc:`microversion_specification`."},{"line_number":50,"context_line":""},{"line_number":51,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":52,"context_line":"follow if it wishes to ensure API compatibility and stability."}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_23536f3a","line":49,"in_reply_to":"ba2be162_d640a109","updated":"2017-03-05 17:55:56.000000000","message":"Done","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":95,"context_line":""},{"line_number":96,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":97,"context_line":"consideration should be given first to the perspective and needs of the end"},{"line_number":98,"context_line":"users of the API (that is those individuals who wish to use the same code"},{"line_number":99,"context_line":"against multiple clouds), second to the deployers and admins of the clouds,"},{"line_number":100,"context_line":"and third to the developers of the service."},{"line_number":101,"context_line":""},{"line_number":102,"context_line":".. note:: For a service that supports :doc:`microversions"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_f67e8568","line":99,"range":{"start_line":98,"start_character":18,"end_line":99,"end_character":23},"updated":"2017-03-03 23:27:30.000000000","message":"You could just abbreviate this as \u0027Monty\u0027.  :)\n\nOtherwise, a comma after \u0027that is\u0027 is needed.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":96,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":97,"context_line":"consideration should be given first to the perspective and needs of the end"},{"line_number":98,"context_line":"users of the API (that is those individuals who wish to use the same code"},{"line_number":99,"context_line":"against multiple clouds), second to the deployers and admins of the clouds,"},{"line_number":100,"context_line":"and third to the developers of the service."},{"line_number":101,"context_line":""},{"line_number":102,"context_line":".. note:: For a service that supports :doc:`microversions"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_a36f5ffa","line":99,"in_reply_to":"ba2be162_f67e8568","updated":"2017-03-05 17:55:56.000000000","message":"Done","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":112,"context_line":"* The change is required to fix a security bug that is so severe that it"},{"line_number":113,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":116,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":117,"context_line":"  upgrade."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_36f81dc3","line":115,"range":{"start_line":115,"start_character":12,"end_line":115,"end_character":26},"updated":"2017-03-03 23:27:30.000000000","message":"Some mention should be made of the OpenStack Vulnerability Management Team, and that it is their opinion that determines if the bug is severe enough.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":112,"context_line":"* The change is required to fix a security bug that is so severe that it"},{"line_number":113,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":114,"context_line":""},{"line_number":115,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":116,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":117,"context_line":"  upgrade."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_836c1b09","line":115,"in_reply_to":"ba2be162_36f81dc3","updated":"2017-03-05 17:55:56.000000000","message":"Done","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":125,"context_line":""},{"line_number":126,"context_line":"The following changes **do** require a version change:"},{"line_number":127,"context_line":""},{"line_number":128,"context_line":"* Adding a new URL."},{"line_number":129,"context_line":""},{"line_number":130,"context_line":"* Changing the response status code from one form of client error to another"},{"line_number":131,"context_line":"  (e.g., ``403`` to ``400``) or one form of success to another (e.g., ``201``"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_561af117","line":128,"range":{"start_line":128,"start_character":18,"end_line":128,"end_character":19},"updated":"2017-03-03 23:27:30.000000000","message":"Add something like:\n\"This may seem backwards-compatible, as old clients would never call the new URL, but it breaks interoperability between clouds.\"","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":125,"context_line":""},{"line_number":126,"context_line":"The following changes **do** require a version change:"},{"line_number":127,"context_line":""},{"line_number":128,"context_line":"* Adding a new URL."},{"line_number":129,"context_line":""},{"line_number":130,"context_line":"* Changing the response status code from one form of client error to another"},{"line_number":131,"context_line":"  (e.g., ``403`` to ``400``) or one form of success to another (e.g., ``201``"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_83b5fb7e","line":128,"in_reply_to":"ba2be162_561af117","updated":"2017-03-05 17:55:56.000000000","message":"Done","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":136,"context_line":"  through changes in success if it treated anything from ``200`` to ``299`` as"},{"line_number":137,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":138,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":139,"context_line":"  explicitly states a specific response code as success, then changing that"},{"line_number":140,"context_line":"  code would require a version change."},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"* Adding or removing a request or response header."}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_76ec55f3","line":139,"range":{"start_line":139,"start_character":2,"end_line":139,"end_character":12},"updated":"2017-03-03 23:27:30.000000000","message":"This second \u0027explicitely\u0027 is not needed.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":136,"context_line":"  through changes in success if it treated anything from ``200`` to ``299`` as"},{"line_number":137,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":138,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":139,"context_line":"  explicitly states a specific response code as success, then changing that"},{"line_number":140,"context_line":"  code would require a version change."},{"line_number":141,"context_line":""},{"line_number":142,"context_line":"* Adding or removing a request or response header."}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_a3a11f48","line":139,"in_reply_to":"ba2be162_76ec55f3","updated":"2017-03-05 17:55:56.000000000","message":"Done","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"797fde4974afa4da1ce89f83e651fd15090647fb","unresolved":false,"context_lines":[{"line_number":223,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":224,"context_line":"from the existing service. When the new service stabilizes it should either"},{"line_number":225,"context_line":"be integrated into the existing service (with a new version) or re-published"},{"line_number":226,"context_line":"as a new (third) service endpoint."},{"line_number":227,"context_line":""},{"line_number":228,"context_line":"Writing a Robust Client"},{"line_number":229,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_15123657","line":226,"updated":"2017-03-03 21:15:37.000000000","message":"Not entirely sure about this paragraph. It\u0027s something we discussed but the details didn\u0027t get nailed down. This is a stab in the dark to prompt some feedback.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9c6b9935f93be64f8238cd2e47c555976470ba6a","unresolved":false,"context_lines":[{"line_number":223,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":224,"context_line":"from the existing service. When the new service stabilizes it should either"},{"line_number":225,"context_line":"be integrated into the existing service (with a new version) or re-published"},{"line_number":226,"context_line":"as a new (third) service endpoint."},{"line_number":227,"context_line":""},{"line_number":228,"context_line":"Writing a Robust Client"},{"line_number":229,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_163eb9c0","line":226,"in_reply_to":"ba2be162_15123657","updated":"2017-03-03 23:27:30.000000000","message":"I would strike the last sentence. The only statuses for an API are CURRENT, SUPPORTED, DEPRECATED, and EXPERIMENTAL. I\u0027m not sure we should have two very similar but incompatible services in the catalog doing the same thing. If it\u0027s a new version that has achieved a sufficient level of stability, move it from EXPERIMENTAL to CURRENT, and move CURRENT to SUPPORTED. It would be preferable, though, to move the new APIs one by one into the current API, with a version bump for each.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"af8f222ce0b5ddf05cad5b973953d52a8dbb20c2","unresolved":false,"context_lines":[{"line_number":223,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":224,"context_line":"from the existing service. When the new service stabilizes it should either"},{"line_number":225,"context_line":"be integrated into the existing service (with a new version) or re-published"},{"line_number":226,"context_line":"as a new (third) service endpoint."},{"line_number":227,"context_line":""},{"line_number":228,"context_line":"Writing a Robust Client"},{"line_number":229,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba2be162_639ba718","line":226,"in_reply_to":"ba2be162_163eb9c0","updated":"2017-03-05 17:55:56.000000000","message":"I\u0027ll see about cooking something more clear. I want to make it clear that only using EXPERIMENTAL is not sufficient (this was a concern that someone (maybe sdague?) expressed in the past...\n\nActually I can\u0027t come up with anything good, so for now I\u0027ll just go with your advice and we can work it out in court.","commit_id":"7d98e0fc5acdb8b845e89d36b0b6056cfe200c8a"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a84de736fd21e144a2e75ffbce58502566e45ab6","unresolved":false,"context_lines":[{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated."},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":39,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a22e58a_d18cf737","line":36,"updated":"2017-03-14 10:37:45.000000000","message":"Nit: Not 100% sure on this being really clear cut. It needs to be discoverable, and you might already have a way to discover that thing. But agreed with where this points.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1a33f58d6c12a4c4fe0b5d3633c69204d1b141d5","unresolved":false,"context_lines":[{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated."},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":39,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a1ff146_9e7c2622","line":36,"in_reply_to":"3a1ff146_1f820d01","updated":"2017-03-15 11:58:34.000000000","message":"I\u0027ve added a blurb here saying \"tbd\"","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"be4c87a1a9c8b81eadb2a742f10dee91e189cefb","unresolved":false,"context_lines":[{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated."},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":39,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a22e58a_d303170c","line":36,"in_reply_to":"5a22e58a_d18cf737","updated":"2017-03-14 11:49:51.000000000","message":"This is one of the things that came up somewhere during the PTG. It was decided that being explicit about what should happen (despite it being a challenge) was the best way to move the doc forward.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"a16e05c196f720c69abfee19c69f8ee74db3a810","unresolved":false,"context_lines":[{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated."},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":39,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a1ff146_1f820d01","line":36,"in_reply_to":"5a22e58a_d303170c","updated":"2017-03-14 21:42:57.000000000","message":"What is the \"equivalent of a major version update\" in the microversion world (where we have URLs including /v1/, etc)? Are we leaving this to be figured out in the future, I guess?","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"574f682db6070f08eae1aa69191f898b57ad4a18","unresolved":false,"context_lines":[{"line_number":102,"context_line":".. note:: For a service that supports :doc:`microversions"},{"line_number":103,"context_line":"          \u003cmicroversion_specification\u003e` we assume here that the client is"},{"line_number":104,"context_line":"          not requesting the ``latest`` version and is either requesting no"},{"line_number":105,"context_line":"          version at all or a specific version."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"Evaluating API Changes"},{"line_number":108,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_36ab6f8b","line":105,"updated":"2017-03-07 12:33:43.000000000","message":"this seems a little non sequitur. As someone who understands why this is here and how it relates, it\u0027s fine. But someone new into the document might find the asside odd.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a4d615cf56776dd58753c10cbbe6755db4e9fb0b","unresolved":false,"context_lines":[{"line_number":102,"context_line":".. note:: For a service that supports :doc:`microversions"},{"line_number":103,"context_line":"          \u003cmicroversion_specification\u003e` we assume here that the client is"},{"line_number":104,"context_line":"          not requesting the ``latest`` version and is either requesting no"},{"line_number":105,"context_line":"          version at all or a specific version."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"Evaluating API Changes"},{"line_number":108,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_b5358247","line":105,"in_reply_to":"9a30ddce_36ab6f8b","updated":"2017-03-07 18:06:49.000000000","message":"Is there a better place to put it? It\u0027s a holdover from an earlier version where microversions were one of several (unenumerated) options for doing versioning. I guess it could be left  out entirely?","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1a33f58d6c12a4c4fe0b5d3633c69204d1b141d5","unresolved":false,"context_lines":[{"line_number":102,"context_line":".. note:: For a service that supports :doc:`microversions"},{"line_number":103,"context_line":"          \u003cmicroversion_specification\u003e` we assume here that the client is"},{"line_number":104,"context_line":"          not requesting the ``latest`` version and is either requesting no"},{"line_number":105,"context_line":"          version at all or a specific version."},{"line_number":106,"context_line":""},{"line_number":107,"context_line":"Evaluating API Changes"},{"line_number":108,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a1ff146_feaa7a6f","line":105,"in_reply_to":"9a30ddce_b5358247","updated":"2017-03-15 11:58:34.000000000","message":"I\u0027ve gone ahead and removed it for now, we can add it as a clarification later.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"a84de736fd21e144a2e75ffbce58502566e45ab6","unresolved":false,"context_lines":[{"line_number":133,"context_line":"  the new URL, but it breaks interoperability between clouds"},{"line_number":134,"context_line":"  presenting the same version of the API but using different code."},{"line_number":135,"context_line":""},{"line_number":136,"context_line":"* Changing the response status code from one form of client error to another"},{"line_number":137,"context_line":"  (e.g., ``403`` to ``400``) or one form of success to another (e.g., ``201``"},{"line_number":138,"context_line":"  to ``204``)."},{"line_number":139,"context_line":""},{"line_number":140,"context_line":"  There continues to be some lingering debate on this topic with regard to"}],"source_content_type":"text/x-rst","patch_set":6,"id":"5a22e58a_a703b975","line":137,"range":{"start_line":136,"start_character":2,"end_line":137,"end_character":28},"updated":"2017-03-14 10:37:45.000000000","message":"In Nova we are allow certain changes if the API is already expecting that error code, and we are just making the response code more accurate within the already expected set.\n\nI think we said 400 (json validation), 404, 403 (policy) are generally always possible from Nova APIs.\n\nThat was probably bad, just wanted to raise that here.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"101ace405baf1c94b6e70de70a4ed136b72575c5","unresolved":false,"context_lines":[{"line_number":140,"context_line":"  There continues to be some lingering debate on this topic with regard to"},{"line_number":141,"context_line":"  changing success codes. A robust client (see below) could effectively ride"},{"line_number":142,"context_line":"  through changes in success if it treated anything from ``200`` to ``299`` as"},{"line_number":143,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":144,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":145,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":146,"context_line":"  require a version change."},{"line_number":147,"context_line":""},{"line_number":148,"context_line":"* Adding or removing a request or response header."},{"line_number":149,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_fe479c1a","line":146,"range":{"start_line":143,"start_character":11,"end_line":146,"end_character":27},"updated":"2017-03-09 00:23:45.000000000","message":"humm, this seems like green/hidden area to make success code change.\n\n\u003eservice documentation has explicitly stated that the broad \u003edefinition of success should be used\nThis you means definition of success should for \n 1. all APIs sever by that service \n 2. per each API\n\nIf 1st case then all ok.\n\nIf 2nd, then it will be difficult to make sure doc compatibility i mean how we make sure projects do not change the definition of success code for that APIs in doc when they want to introduced success code change.\n\nFor 2nd case, I am afraid if project keep changing those APIs success code definition, something like below -\nWhen project want to change success code then they can: \n - change doc first to say broad definition of success is accepted\n - then change success code.\n\nat some point later change doc again to reflect the specific success code.\n\nI know that\u0027s bad way but this relaxation can leads to controversy again. Mainly from QA and new API stability tag perceptive.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"406a028129022986cd380bfd1a320228ea81942c","unresolved":false,"context_lines":[{"line_number":140,"context_line":"  There continues to be some lingering debate on this topic with regard to"},{"line_number":141,"context_line":"  changing success codes. A robust client (see below) could effectively ride"},{"line_number":142,"context_line":"  through changes in success if it treated anything from ``200`` to ``299`` as"},{"line_number":143,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":144,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":145,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":146,"context_line":"  require a version change."},{"line_number":147,"context_line":""},{"line_number":148,"context_line":"* Adding or removing a request or response header."},{"line_number":149,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_52bdd300","line":146,"range":{"start_line":143,"start_character":11,"end_line":146,"end_character":27},"in_reply_to":"9a30ddce_fe479c1a","updated":"2017-03-09 20:31:27.000000000","message":"this just seems like it\u0027s an issue for the teams to make sure they properly documenting the changes to their APIs, or am i missing a nuance?","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10608,"name":"Matthew Edmonds","email":"edmondsw@us.ibm.com","username":"edmondsw"},"change_message_id":"7239643274aa339c8c7323d222192edeeea04f30","unresolved":false,"context_lines":[{"line_number":225,"context_line":"(in the standard English sense) has been reached is it worth considering."},{"line_number":226,"context_line":""},{"line_number":227,"context_line":"A project which has an existing stable service that wants to experiment with"},{"line_number":228,"context_line":"new functionality that it may choose to never stabilize should publish that"},{"line_number":229,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":230,"context_line":"from the existing service."},{"line_number":231,"context_line":""},{"line_number":232,"context_line":"Writing a Robust Client"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_c3ced259","line":229,"range":{"start_line":228,"start_character":56,"end_line":229,"end_character":64},"updated":"2017-03-07 13:32:47.000000000","message":"I don\u0027t think that\u0027s possible without breaking the rules for how the service catalog is supposed to be used. See https://etherpad.openstack.org/p/service-catalog-pike and run this by the Keystone folks.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a4d615cf56776dd58753c10cbbe6755db4e9fb0b","unresolved":false,"context_lines":[{"line_number":226,"context_line":""},{"line_number":227,"context_line":"A project which has an existing stable service that wants to experiment with"},{"line_number":228,"context_line":"new functionality that it may choose to never stabilize should publish that"},{"line_number":229,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":230,"context_line":"from the existing service."},{"line_number":231,"context_line":""},{"line_number":232,"context_line":"Writing a Robust Client"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_f5545a55","line":229,"in_reply_to":"9a30ddce_c3ced259","updated":"2017-03-07 18:06:49.000000000","message":"That it is breaking the rules is sort of the point. Having it as a wart in the service catalog highlights the ephemeral nature of the thing.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"574f682db6070f08eae1aa69191f898b57ad4a18","unresolved":false,"context_lines":[{"line_number":241,"context_line":"When writing a client that makes several requests (to the same service) to"},{"line_number":242,"context_line":"perform a task, it can be useful to express an explicit microversion for each"},{"line_number":243,"context_line":"individual request, especially in the case where older behavior is being used."},{"line_number":244,"context_line":"There is no requirement to use the same version for every request."},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"*Accept success or client failure broadly.*"},{"line_number":247,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_56038373","line":244,"updated":"2017-03-07 12:33:43.000000000","message":"I\u0027m a little concerned in putting this in here, because what it does it makes client code that doesn\u0027t work with all services that have version 2.25, but only services that have 2.0 \u003c\u003d\u003e 2.25. Because we\u0027ve not yet seen minimum bumps, that\u0027s been fine, however when we do start seeing them it\u0027s actually encouraging a more fragile behavior.\n\nWhen the user dove in to docs to extend their program to 2.25, it is an excellent time to make sure the whole script runs at that level (they have taken the time to read docs, test code with new features).","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"a16e05c196f720c69abfee19c69f8ee74db3a810","unresolved":false,"context_lines":[{"line_number":241,"context_line":"When writing a client that makes several requests (to the same service) to"},{"line_number":242,"context_line":"perform a task, it can be useful to express an explicit microversion for each"},{"line_number":243,"context_line":"individual request, especially in the case where older behavior is being used."},{"line_number":244,"context_line":"There is no requirement to use the same version for every request."},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"*Accept success or client failure broadly.*"},{"line_number":247,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a1ff146_5f6d6531","line":244,"in_reply_to":"9a30ddce_55fa8643","updated":"2017-03-14 21:42:57.000000000","message":"+1 to removing this.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a4d615cf56776dd58753c10cbbe6755db4e9fb0b","unresolved":false,"context_lines":[{"line_number":241,"context_line":"When writing a client that makes several requests (to the same service) to"},{"line_number":242,"context_line":"perform a task, it can be useful to express an explicit microversion for each"},{"line_number":243,"context_line":"individual request, especially in the case where older behavior is being used."},{"line_number":244,"context_line":"There is no requirement to use the same version for every request."},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"*Accept success or client failure broadly.*"},{"line_number":247,"context_line":""}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a30ddce_55fa8643","line":244,"in_reply_to":"9a30ddce_56038373","updated":"2017-03-07 18:06:49.000000000","message":"Sean and I discussed this in IRC. This was placed in the doc to record some discussion at the PTG. It probably makes more sense to have this section as a separate document that gets review separately. I\u0027ll remove it in the next revision unless there is clamoring.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"a16e05c196f720c69abfee19c69f8ee74db3a810","unresolved":false,"context_lines":[{"line_number":247,"context_line":""},{"line_number":248,"context_line":"If the only thing that matters when making a request is knowing that it works"},{"line_number":249,"context_line":"or it didn\u0027t then don\u0027t check the response for an explicit response code."},{"line_number":250,"context_line":"Instead branch on ``200 \u003c\u003d status \u003c 300``."},{"line_number":251,"context_line":""},{"line_number":252,"context_line":""},{"line_number":253,"context_line":"References"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a1ff146_3f5fc973","line":250,"updated":"2017-03-14 21:42:57.000000000","message":"nit: maybe add \"e.g.\" or \"for example\" here.","commit_id":"b2e1ce5d023483e12560471287d451b2f800b964"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":23,"context_line":"* The changes must not violate compatibility nor stability, both of which"},{"line_number":24,"context_line":"  are defined in more detail below."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_b4dae176","line":28,"range":{"start_line":26,"start_character":0,"end_line":28,"end_character":30},"updated":"2017-03-15 12:50:21.000000000","message":"This is nice, but impossible to implement in many projects featuring drivers. And definitely not in projects featuring 3rdparty API extensions (Ironic and Neutron come to my mind). \n\nAlso, the way it\u0027s worded here (I understand it\u0027s not the intention), it rules out e.g Mistral, as it\u0027s requests and responses are by definitions 1. changeable by users, 2. pluggable by operators.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_7a15189a","line":28,"in_reply_to":"1a1ced50_10f9bc4d","updated":"2017-03-22 15:34:08.000000000","message":"\u003e To the driver question, I would say that if deployment A and deployment B are using the same version of the same driver, identical requests would result in identical responses.\n\nThis is true, but how to express this in terms of API microversions? For ironic the \"leakyness\" of the abstraction is too big to ignore IMO. E.g. power action availability depends on a driver, certain features like RAID too.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_eaab6687","line":28,"in_reply_to":"3a1ff146_04db7d7d","updated":"2017-03-16 12:21:50.000000000","message":"My interpretation of this guidance has been to consider it in terms of \"interoperability\" which essentially means:\n\n* you can\u0027t claim to be interoperable if different drivers result in different apis, so either don\u0027t have different apis (a less leaky abstraction) or don\u0027t have drivers\n\n* if you can\u0027t do that, then the \"passthrough\" concept has to be treated as legit\n\nThe point of writing this stuff down is to make it really clear what a commitment to inter-cloud interoperability really means and how hard it is to truly achieve.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"d4e5fdc1f7c5bd97b309563b5341a62ecde8ab1f","unresolved":false,"context_lines":[{"line_number":23,"context_line":"* The changes must not violate compatibility nor stability, both of which"},{"line_number":24,"context_line":"  are defined in more detail below."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_04db7d7d","line":28,"range":{"start_line":26,"start_character":0,"end_line":28,"end_character":30},"in_reply_to":"3a1ff146_433572d8","updated":"2017-03-15 15:53:05.000000000","message":"Sure, maybe it\u0027s an excuse, but it depends how the API is defined, IMO.\n\nWe\u0027ve learned in the past that people will always put experimental things in production, and then complain when they\u0027re broken. Let\u0027s not do that :)","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"f908cc6f14217ca510ba1593d98ad0fa995f5e61","unresolved":false,"context_lines":[{"line_number":23,"context_line":"* The changes must not violate compatibility nor stability, both of which"},{"line_number":24,"context_line":"  are defined in more detail below."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_433572d8","line":28,"range":{"start_line":26,"start_character":0,"end_line":28,"end_character":30},"in_reply_to":"3a1ff146_801200b3","updated":"2017-03-15 13:58:53.000000000","message":"This sounds an excuse to me :) We can\u0027t say our whole API is stable and compatible (within the definition of this spec) with it.\n\nWhich raises a good question: should we explicitly spell out something like \"experimental\" API, which is also explicitly out of scope for this proposal? Such API would require an explicit (again) header to be send, like X-OpenStack-Experimental-Api: baremetal(vendor-drac)?","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"33f3cff316e5164e4505aa9824396f265f964a62","unresolved":false,"context_lines":[{"line_number":23,"context_line":"* The changes must not violate compatibility nor stability, both of which"},{"line_number":24,"context_line":"  are defined in more detail below."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_801200b3","line":28,"range":{"start_line":26,"start_character":0,"end_line":28,"end_character":30},"in_reply_to":"3a1ff146_b4dae176","updated":"2017-03-15 13:46:36.000000000","message":"Ironic has always defined its \"vendor passthru\" APIs in such a way that the semantics of those APIs are stable, including the semantic of e.g. \"/methods will changed based on which drivers are loaded\". I tend to think that\u0027s fine, so long as it\u0027s properly documented, and meets the spirit of this spec, if not the letter.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1acafed22d71bce022b78605c6ff5347f84d10fc","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":"* Changes in resources and request and response bodies and headers are not"},{"line_number":27,"context_line":"  allowed without signalling a version boundary, except in a very small"},{"line_number":28,"context_line":"  number of cases (see below)."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_10f9bc4d","line":28,"in_reply_to":"3a1ff146_eaab6687","updated":"2017-03-20 23:15:25.000000000","message":"Right. To the driver question, I would say that if deployment A and deployment B are using the same version of the same driver, identical requests would result in identical responses.\n\n@Dmitry: establishing an Experimental API would involve creating a separate endpoint.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."},{"line_number":32,"context_line":""},{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_d4be7dfe","line":34,"range":{"start_line":33,"start_character":2,"end_line":34,"end_character":15},"updated":"2017-03-15 12:50:21.000000000","message":"This is good, but impractical to the extent of not being worth bothering with, especially in view of my previous comment.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."},{"line_number":32,"context_line":""},{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_daa1ac47","line":34,"range":{"start_line":33,"start_character":2,"end_line":34,"end_character":15},"in_reply_to":"1a1ced50_3064f820","updated":"2017-03-22 15:34:08.000000000","message":"\u003e If your API is still changing as the project evolves and you learn what is needed and what works well, you are pretty much the definition of an unstable API\n\nThis means that nearly all API in the world is unstable :) which is something I\u0027m fine with, for the record.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"33f3cff316e5164e4505aa9824396f265f964a62","unresolved":false,"context_lines":[{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."},{"line_number":32,"context_line":""},{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_e08814ea","line":34,"range":{"start_line":33,"start_character":2,"end_line":34,"end_character":15},"in_reply_to":"3a1ff146_d4be7dfe","updated":"2017-03-15 13:46:36.000000000","message":"The alternative is breaking those APIs without indicating there is a change, so I think it is worth bothering with :)","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"f908cc6f14217ca510ba1593d98ad0fa995f5e61","unresolved":false,"context_lines":[{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."},{"line_number":32,"context_line":""},{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_e3f81ee8","line":34,"range":{"start_line":33,"start_character":2,"end_line":34,"end_character":15},"in_reply_to":"3a1ff146_e08814ea","updated":"2017-03-15 13:58:53.000000000","message":"What I mean is the following example. Ironic Inspector has API version 1.0 with introspection endpoint accepting parameters new_ipmi_username and new_ipmi_password. These are documented as experimental, and required a config option to be available.\n\nThey\u0027re terrible, and we want to remove it. Not only disable in later API versions, that would leave a lot of bad code around. Actually remove.\n\nNow, what this spec suggests is for us to stop supporting API 1.0. So instead of potentially breaking a few users playing with an experimental and half-baked feature, we break everyone (after a looong deprecation period) using API 1.0. Even if they never thought about this tiny feature. This is in spirit of this spec, but it is.. bad.\n\nAgain, experimental API would help.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1acafed22d71bce022b78605c6ff5347f84d10fc","unresolved":false,"context_lines":[{"line_number":30,"context_line":"* Version discovery and selection should default to a baseline; changes are"},{"line_number":31,"context_line":"  opt-in."},{"line_number":32,"context_line":""},{"line_number":33,"context_line":"* When functionality is fully removed, this must result in the baseline"},{"line_number":34,"context_line":"  being raised. Ideally this should result in the equivalent of a major"},{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_3064f820","line":34,"range":{"start_line":33,"start_character":2,"end_line":34,"end_character":15},"in_reply_to":"3a1ff146_e3f81ee8","updated":"2017-03-20 23:15:25.000000000","message":"Agree. If your API is still changing as the project evolves and you learn what is needed and what works well, you are pretty much the definition of an unstable API. :) You would not be applying for this tag until much later when you can feel confident that the API is indeed stable.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_b448212f","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"updated":"2017-03-15 12:50:21.000000000","message":"No, this has to be addressed right now, as this spec demands it.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_da3d2cde","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"in_reply_to":"1a1ced50_703cb0e2","updated":"2017-03-22 15:34:08.000000000","message":"My comment is here because I don\u0027t like the word \"must\" applied to a concept which is not even defined clearly.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_6ac5b63a","line":39,"in_reply_to":"3a1ff146_4453b5e1","updated":"2017-03-16 12:21:50.000000000","message":"In the microversion context, raising the minimum is somewhat akin to a major version (in semver terms) and there are plenty of people who think it should _never_ happen but there are plenty of other people who think it should. Since we don\u0027t have  a lot of experience in actually doing it, trying to codify something is...hard. So better to simply say \"we need to figure this out\" rather than delaying forever?","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"6b37a5d553f70ab638dc221577092d0a9cf0ee11","unresolved":false,"context_lines":[{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_70c84423","line":39,"in_reply_to":"3a1ff146_6ac5b63a","updated":"2017-03-16 12:33:51.000000000","message":"@cdent, yeah, I\u0027m fine with the wording here to leave it for the future. Primarily because I have a proposal/experiment for how we raise the minimum, so I don\u0027t think it\u0027s a distant future. :)\n\nhttps://review.openstack.org/#/c/446138/\nhttps://review.openstack.org/#/c/446167/","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"d4e5fdc1f7c5bd97b309563b5341a62ecde8ab1f","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_4453b5e1","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"in_reply_to":"3a1ff146_83376aaf","updated":"2017-03-15 15:53:05.000000000","message":"Yes, I believe we need to be able to do that (with very long deprecation periods and such) to be able to effectively make progress with our APIs long term.\n\nFWIW, I\u0027m working on a spec right now about raising the minimum microversion.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"f908cc6f14217ca510ba1593d98ad0fa995f5e61","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_83376aaf","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"in_reply_to":"3a1ff146_a0bb7cc3","updated":"2017-03-15 13:58:53.000000000","message":"Raising minimum microversion implies removing old microversions. This may or not be in spirit of this spec, but removing a microversion means breaking all clients using it.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"33f3cff316e5164e4505aa9824396f265f964a62","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_a0bb7cc3","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"in_reply_to":"3a1ff146_b448212f","updated":"2017-03-15 13:46:36.000000000","message":"I\u0027m very curious how we address this, as it seems really hard to actually bump the major. My assumption until now is that we just raise minimum microversion, which is why I asked what a \"major version update\" might look like.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1acafed22d71bce022b78605c6ff5347f84d10fc","unresolved":false,"context_lines":[{"line_number":35,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":36,"context_line":"  violated. At this time \"major version update\" is not fully defined, in"},{"line_number":37,"context_line":"  part because different services present versions differently (e.g., some"},{"line_number":38,"context_line":"  services have a version in their URLs). This will need to be addressed in"},{"line_number":39,"context_line":"  future work."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":42,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_703cb0e2","line":39,"range":{"start_line":38,"start_character":42,"end_line":39,"end_character":14},"in_reply_to":"3a1ff146_b448212f","updated":"2017-03-20 23:15:25.000000000","message":"It \"demands\" that you do a major update; it doesn\u0027t specify exactly how that must occur. Maybe it\u0027s a new API major version; maybe it\u0027s a series of deprecation warnings over a few release cycles; maybe it\u0027s something else. But it must be something clearly visible to consumers of the API.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":52,"context_line":"goals described here are :doc:`microversions \u003cmicroversion_specification\u003e`."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":55,"context_line":"follow if it wishes to ensure API compatibility and stability."},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"Any service which does not support versioning SHOULD do two things:"},{"line_number":58,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_f448d95d","line":55,"range":{"start_line":55,"start_character":13,"end_line":55,"end_character":61},"updated":"2017-03-15 12:50:21.000000000","message":"a bit strongly worded. please put it \"wishes to comply with this recommendation\". there are different approaches to the goals you stated, and different degrees of API compatibility and stability projects may want (or be able to) imply. E.g. this spec is strictly speaking impossible to implement in Ironic (not without rewriting it), nor do I find it valuable enough to bother with.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":52,"context_line":"goals described here are :doc:`microversions \u003cmicroversion_specification\u003e`."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":55,"context_line":"follow if it wishes to ensure API compatibility and stability."},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"Any service which does not support versioning SHOULD do two things:"},{"line_number":58,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_9d2c8e9a","line":55,"in_reply_to":"1a1ced50_b00d4840","updated":"2017-03-22 15:34:08.000000000","message":"\u003e Why should the standard in this document be weakened?\n\nNot sure what you mean by \"weakened\". This wording presents the solution here as the only solution.\n\nIf we talk about a tag - yes, let\u0027s talk about a tag. I just don\u0027t want to hear \"your project API is not compatible\" based on not compliant with this particular approach to it.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":52,"context_line":"goals described here are :doc:`microversions \u003cmicroversion_specification\u003e`."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":55,"context_line":"follow if it wishes to ensure API compatibility and stability."},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"Any service which does not support versioning SHOULD do two things:"},{"line_number":58,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_ea8366ca","line":55,"in_reply_to":"3a1ff146_00643e47","updated":"2017-03-16 12:21:50.000000000","message":"The goal of this document is to define what must be done, with the tools that are available in the openstack context, in order to achieve interoperability and consistency. This means that existing precedents have a fair amount of power despite there being other options.\n\nAs with all API-WG guidelines, this is a guideline. The advice is: if you want to achieve what\u0027s described here, then do this to be in alignment with the common trend. There\u0027s no requirement to be in alignment, but it is considered a good idea.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1acafed22d71bce022b78605c6ff5347f84d10fc","unresolved":false,"context_lines":[{"line_number":52,"context_line":"goals described here are :doc:`microversions \u003cmicroversion_specification\u003e`."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":55,"context_line":"follow if it wishes to ensure API compatibility and stability."},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"Any service which does not support versioning SHOULD do two things:"},{"line_number":58,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_b00d4840","line":55,"in_reply_to":"3a1ff146_ea8366ca","updated":"2017-03-20 23:15:25.000000000","message":"Well, to be fair, it will be more than a guideline if it is used as the basis for the API stability tag from the TC. And that\u0027s a good thing, since we want that tag to have a clear definition.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"9bb925e61d1d859c80475d6a5fb76ffcc4f2e62b","unresolved":false,"context_lines":[{"line_number":52,"context_line":"goals described here are :doc:`microversions \u003cmicroversion_specification\u003e`."},{"line_number":53,"context_line":""},{"line_number":54,"context_line":"The rest of this document will describe the rules that a service MUST"},{"line_number":55,"context_line":"follow if it wishes to ensure API compatibility and stability."},{"line_number":56,"context_line":""},{"line_number":57,"context_line":"Any service which does not support versioning SHOULD do two things:"},{"line_number":58,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_00643e47","line":55,"range":{"start_line":55,"start_character":13,"end_line":55,"end_character":61},"in_reply_to":"3a1ff146_f448d95d","updated":"2017-03-15 20:22:02.000000000","message":"Why should the standard in this document be weakened? A project can elect to not conform without issue. Some of the commentary on this patch set seems to hinge on this question.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":63,"context_line":""},{"line_number":64,"context_line":".. note:: A project which does not have a robust system for managing"},{"line_number":65,"context_line":"          version boundaries but must make changes to their API is by"},{"line_number":66,"context_line":"          definition not adhering to the guidelines for compatibility and"},{"line_number":67,"context_line":"          stability. The project itself must make the decisions on how to"},{"line_number":68,"context_line":"          evolve their API. If this leads to conflicts with other projects"},{"line_number":69,"context_line":"          within the OpenStack ecosystem, the role of the API-WG is solely"},{"line_number":70,"context_line":"          to help clarify the guidelines and provide advice on how to"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_94e7a511","line":67,"range":{"start_line":66,"start_character":37,"end_line":67,"end_character":19},"updated":"2017-03-15 12:50:21.000000000","message":"\"this particular guideline\".","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":77,"context_line":"up\"."},{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_9495e541","line":81,"range":{"start_line":80,"start_character":40,"end_line":81,"end_character":11},"updated":"2017-03-15 12:50:21.000000000","message":"-1. If you demand versioning, it has to be in place from day 0, even if the remaining guidelines is not adhered to. Without versioning ever in place, clients will have to guess whether versioning works or not (we do it in ironicclient, not quite fun).","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_5db4d633","line":81,"in_reply_to":"1a1ced50_9ba94de2","updated":"2017-03-22 15:34:08.000000000","message":"\u003e We\u0027re talking about bleeding edge here, right? What would typically be called \u0027alpha\u0027?\n\nNo. We are talking about a long period of establishing API, which is often done by trying it in field. Unstable API does not necessary mean that software itself is not stable.\n\nI agree that during alpha period versioning is not needed. But there is a big period of time between \"first put in production\" and \"achieved stability and interoperability according to this api-wg guideline\". It can take years.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"0ce31a4b69585ba5e1da7d3193ddaa96f78b3895","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_0e5c814a","line":81,"in_reply_to":"3a1ff146_0055304f","updated":"2017-03-15 14:33:26.000000000","message":"The reason this is not recommended is because there are concerns that once you have (addressable) versions in place you have to keep them as people will rely on them and then you can\u0027t take them away. The idea is until there are versions, bets are off. I\u0027m not sure if that\u0027s correct, but that\u0027s the rationale.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"d4e5fdc1f7c5bd97b309563b5341a62ecde8ab1f","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_64ba71e3","line":81,"in_reply_to":"3a1ff146_090abb26","updated":"2017-03-15 15:53:05.000000000","message":"@cdent I guess the reason I would recommend a version from the beginning is, then clients don\u0027t need to deal with compatibility between \"service before it had versioning\" and \"service after it had versioning\".","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"aee9ad15c960ccbd18d891a3e39d97cfc103edbc","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_090abb26","line":81,"in_reply_to":"3a1ff146_0e5c814a","updated":"2017-03-15 14:42:52.000000000","message":"\u003e you can\u0027t take them away\n\nI\u0027ve read it somewhere, but can\u0027t find now: do we expect versions to never be removed? this is fine with me, but in spirit of this spec it means that functionality can never be removed, as long as it was ever somehow exposed in API.. Not sure it\u0027s acceptable (see my example somewhere here).","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_6a94d6e1","line":81,"in_reply_to":"3a1ff146_16cba11f","updated":"2017-03-16 12:21:50.000000000","message":"So if we say something like \"versions less than 1\" are unstable by definition we are creating some conflation with semver and that\u0027s very much something microversions don\u0027t want to do. All they are supposed to say is version X is not version Y.\n\nI can change this paragraph, somehow, but at this point it is not clear how.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"a1579d84cd3aaa8f07af839913fe703089039648","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_9744fd74","line":81,"in_reply_to":"3a1ff146_64ba71e3","updated":"2017-03-15 16:43:56.000000000","message":"I\u0027ll jump on with jroll here, even with the rapid changes going on in early development, as an API consumer I need _some_ indication of _which_ API I am dealing with.  Defining everything that is \"pre-initial-release\" as a single release meets the letter of the guideline, but is infuriating to actually use unless the road to initial release is short.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"129cb6108f2d293b65a133c7abceb40f91fbd4dc","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_ba2560ac","line":81,"in_reply_to":"3a1ff146_64ba71e3","updated":"2017-03-15 16:36:08.000000000","message":"Maybe have a version \u003c 1, which implies less stability.  Once you reach some stability, bump the version to 1.0 (making all the clients update) and start microversioning.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"1acafed22d71bce022b78605c6ff5347f84d10fc","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_9ba94de2","line":81,"in_reply_to":"3a1ff146_64ba71e3","updated":"2017-03-20 23:15:25.000000000","message":"We\u0027re talking about bleeding edge here, right? What would typically be called \u0027alpha\u0027? Where the contract is \"there is no contract yet\".  :)\n\nI would say that the concept of versioning should be baked into a project\u0027s API from the start, but having to make documented releases and notes during an alpha period is counter-productive. Anyone using such software is an adult and knows not to expect things to be unchanging.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"33f3cff316e5164e4505aa9824396f265f964a62","unresolved":false,"context_lines":[{"line_number":77,"context_line":"up\"."},{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_0055304f","line":81,"range":{"start_line":80,"start_character":40,"end_line":81,"end_character":11},"in_reply_to":"3a1ff146_9495e541","updated":"2017-03-15 13:46:36.000000000","message":"Good point, I tend to agree with this. We should be recommending projects ship a version 1.0 or so immediately.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"219030fa37cde8da36824ec304045ed13266241a","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"A service which is new and under development will obviously be undergoing a"},{"line_number":80,"context_line":"great deal of change in its early days. During this time versioning is"},{"line_number":81,"context_line":"superfluous. However, once there has been a release or a dependency created"},{"line_number":82,"context_line":"with another service, stability, compatibility and thus versioning become"},{"line_number":83,"context_line":"important."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_16cba11f","line":81,"in_reply_to":"3a1ff146_9744fd74","updated":"2017-03-15 22:26:54.000000000","message":"That is a nice point.\n\n \u003e Maybe have a version \u003c 1, which implies less stability.\n\nI tend to agree with the above thinking. At early stage of the development(v0.9-), we don\u0027t have many clients and the effect area is very small. Maybe the client is only a single for the development purpose at this situation. So I feel versioning could be a little overkill in this case.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"219030fa37cde8da36824ec304045ed13266241a","unresolved":false,"context_lines":[{"line_number":90,"context_line":""},{"line_number":91,"context_line":"**compatibility**"},{"line_number":92,"context_line":"  An API is compatible when client code written for that service on cloud"},{"line_number":93,"context_line":"  `A` will work without changes with the same service on cloud `B`."},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_56a3594f","line":93,"updated":"2017-03-15 22:26:54.000000000","message":"Nice description, the **compatibility** means **interoperability** IIUC.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":88,"context_line":"For the sake of these guidelines the terms `compatibility` and `stability`"},{"line_number":89,"context_line":"are given fairly narrow definitions:"},{"line_number":90,"context_line":""},{"line_number":91,"context_line":"**compatibility**"},{"line_number":92,"context_line":"  An API is compatible when client code written for that service on cloud"},{"line_number":93,"context_line":"  `A` will work without changes with the same service on cloud `B`."},{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_d4ad9d89","line":97,"range":{"start_line":91,"start_character":0,"end_line":97,"end_character":42},"updated":"2017-03-15 12:50:21.000000000","message":"Neither of this implies any versioning. The only thing it implies is to never make breaking changes (for vast definition of breaking), and for client to use common sense (which is always the requirement, even with your guideline).\n\nPlease expand on how these requirements end up in this spec, except for \"this is how we like to do it for some time\".","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"459a42eb8750137ab7849b1c11fd5104050eb827","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_b7077080","line":97,"in_reply_to":"1a1ced50_09710d78","updated":"2017-03-23 16:32:48.000000000","message":"This assumes that the goal of your application is to receive 404. But it\u0027s probably not. So you request version N+1, which works on Cloud A, but fails on Cloud B. Here is your difference in behaviours.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"12ec1d9196a2643c1d2c4375abe02b80defca1a5","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_cd52d366","line":97,"in_reply_to":"1a1ced50_1d717e76","updated":"2017-03-22 17:08:25.000000000","message":"Dmitry - it seems that your concern is single-cloud only. IOW, if Cloud A adds a new resource via a new URL, client code written for that cloud will continue to work fine, as it doesn\u0027t know about the new URL. But in a multi-cloud world (what I like to call \"Monty\u0027s world\" :), if I write a client that talks to Cloud A and requests that new URL, and then try the same thing on Cloud B, which has the same published version, but has not yet upgraded to the \"non-breaking\" change, I will not get the same response. So here we have two clouds both telling us that they are on the same version, but we have two very different behaviors.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"2b70ed5aba0edfc56351a6b74390b34756b2ea7d","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_7802450d","line":97,"in_reply_to":"1a1ced50_1dda23ea","updated":"2017-03-23 17:39:36.000000000","message":"That would work if you bump the software version every time you make an API change...and that\u0027s effectively what a microversion is.\n\nAnd you still need the rest of the stuff in this document which describes when you do and don\u0027t need to bump the version.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"c243381a2f071a0c0abd7fd00dd68a844f3f1094","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_1dda23ea","line":97,"in_reply_to":"1a1ced50_5dc3bb38","updated":"2017-03-23 17:09:46.000000000","message":"Yes, this is how it has to work. But here is a caveat: it does not require hiding features, or nearly anything in this document. It only requires the server to publish its version. I\u0027m not even saying \"API version\", software version is even enough.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"690af8f625eca034b52f3675823b2ad0f09955bd","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_09710d78","line":97,"in_reply_to":"1a1ced50_90f550ee","updated":"2017-03-23 15:55:28.000000000","message":"Of course it will. In the microversion world, adding the URL would require a new microversion, Cloud A would now be a version N+1, while Cloud B would be at N. And a request for that new URL to both clouds at version N would return 404.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"4e66aadf70d9c01f184f1382f59067586b2168d6","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_5dc3bb38","line":97,"in_reply_to":"1a1ced50_b7077080","updated":"2017-03-23 17:05:01.000000000","message":"Suppose your application wants feature X, and knows that feature X is only available as of microversion Y.  You query clouds A and B asking them what microversion they support, and that tells you that cloud B doesn\u0027t support feature X.  This is how nova works currently, for example.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0b74024816fd7006e71854fa6d6c937fb66a96a7","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_90f550ee","line":97,"in_reply_to":"1a1ced50_cd52d366","updated":"2017-03-22 17:14:55.000000000","message":"No, sorry, my concern is any-cloud. You cannot get the same experience on 2 clouds, by requesting a feature that just does not exist on one of them. Versioning does strictly zero to fix it, only change the error code will differ in your example (404 vs 406).\n\nAs to your last comment, it gets solved by publishing available versions, but not by hiding new features behind explicit version requests.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_aa4a4e81","line":97,"in_reply_to":"3a1ff146_341eea63","updated":"2017-03-16 12:21:50.000000000","message":"Dmitry, what\u0027s a \"non breaking change\"?\n\nThis entire document is trying to indicate that any change is in fact breaking in a world where there is more than one cloud and each cloud is running different releases of code.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"129cb6108f2d293b65a133c7abceb40f91fbd4dc","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_9af3440a","line":97,"in_reply_to":"3a1ff146_341eea63","updated":"2017-03-15 16:36:08.000000000","message":"If you don\u0027t ever make breaking changes you end up like the linux kernel with five variations of the same syscall with slightly different parameters, and the only way for clients to tell if one is supported is to try it and see if it fails.\n\nHaving versions lets you have a single API call, with the client/server agreeing on the parameters.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_1d717e76","line":97,"in_reply_to":"3a1ff146_aa4a4e81","updated":"2017-03-22 15:34:08.000000000","message":"\u003e Dmitry, what\u0027s a \"non breaking change\"?\n\nKinda philosophical question :) A change violating this assumption (caveat: for some reasonably written clients).\n\nI guess it boils down to defining \"reasonably written client\". In my opinion, a client that break from adding an endpoint is not reasonably written.\n\n/me knows examples of software that breaks when sees a new field in the JSON structure returned from API. Sigh...","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"aee9ad15c960ccbd18d891a3e39d97cfc103edbc","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_341eea63","line":97,"in_reply_to":"3a1ff146_c9cfc3ae","updated":"2017-03-15 14:42:52.000000000","message":"\u003e Versioning is the inevitable result of the definitions above combined\n\nThis is something I challenge. Just not ever having breaking changes achieves the same purpose with non-technical means.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"0ce31a4b69585ba5e1da7d3193ddaa96f78b3895","unresolved":false,"context_lines":[{"line_number":94,"context_line":""},{"line_number":95,"context_line":"**stability**"},{"line_number":96,"context_line":"  An API is stable when client code written at time `X` will continue to"},{"line_number":97,"context_line":"  work without changes at future time `Y`."},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"When there is doubt in how these definitions should be applied to a situation"},{"line_number":100,"context_line":"consideration should be given first to the perspective and needs of the end"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_c9cfc3ae","line":97,"in_reply_to":"3a1ff146_d4ad9d89","updated":"2017-03-15 14:33:26.000000000","message":"This is a guideline about compatibility and stability not about versioning. Versioning is the inevitable result of the definitions above combined with the fact that change will happen and compatibility between installations is required. The concept of interoperability is built into the OpenStack mission, it\u0027s an immutable given.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":107,"context_line":""},{"line_number":108,"context_line":"There are two types of change which **do not** require a version change:"},{"line_number":109,"context_line":""},{"line_number":110,"context_line":"* The change is required to fix a security bug that is so severe that it"},{"line_number":111,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_b4ce6158","line":111,"range":{"start_line":110,"start_character":0,"end_line":111,"end_character":64},"updated":"2017-03-15 12:50:21.000000000","message":"I understand the point of this exclusion, but it really stretches the definition of \"stable and compatible\" you\u0027ve just set. Now, a follow-up question will be: is it acceptable to fix a severe data loss?","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"a1579d84cd3aaa8f07af839913fe703089039648","unresolved":false,"context_lines":[{"line_number":111,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_1a91149a","line":114,"updated":"2017-03-15 16:43:56.000000000","message":"Clarity on what is the \"new version\" here may be helpful.  New API version or new implementation release/version?\n\nAgain, making changes to an API that a client is unable to detect is simply bad UX.  This feels like it goes back to the \"hide the sendmail version in the banner\" tactic, which really just resulted in brute-force attacks hoping that the vulnerable release was still in place even if it didn\u0027t announce itself.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"219030fa37cde8da36824ec304045ed13266241a","unresolved":false,"context_lines":[{"line_number":111,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_c9308eeb","line":114,"in_reply_to":"3a1ff146_1a91149a","updated":"2017-03-15 22:26:54.000000000","message":"Yeah, a nice point. I think that is the weakness of current microversion. Current versioning schema is X.Y and Y continues increasing on microversion. If we need to notifies \"security fix\" with versioning, the same microversion of different branches(eg: Ocata and Newton) means different API behavior.. So we cannot use microversion to notify \"security fix\" at this time.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":110,"context_line":"* The change is required to fix a security bug that is so severe that it"},{"line_number":111,"context_line":"  requires backporting to all supported releases of the service."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_74030974","line":115,"range":{"start_line":113,"start_character":28,"end_line":115,"end_character":10},"updated":"2017-03-15 12:50:21.000000000","message":"This is *never* the correct answer, please drop or rephrase it. If there is a version, exposing a security issue, it *will* be used to attack.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_7db992cb","line":115,"in_reply_to":"3a1ff146_501a686f","updated":"2017-03-22 15:34:08.000000000","message":"So, then this boils down to:\n\n For security issues, depending on severity assigned by the VMT, we either fix it across all versions, or don\u0027t fix it at all.\n\nLet\u0027s phrase it like that, it\u0027s not a \"fix\" if you can bypass it by specifying an old version.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_501a686f","line":115,"in_reply_to":"3a1ff146_69316f0b","updated":"2017-03-16 12:21:50.000000000","message":"That\u0027s the point on the caveat of the VMT getting to decide. If the vulnerability is significant, then ever release which is still supported (thus meaning every api version) will be fixed.\n\nIf it is not significant, it won\u0027t be.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"0ce31a4b69585ba5e1da7d3193ddaa96f78b3895","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_a9b447f2","line":115,"in_reply_to":"3a1ff146_74030974","updated":"2017-03-15 14:33:26.000000000","message":"This is exactly the answer discussed and described at the PTG. It is trying to capture the belief (in the room at the time) that there are some mild security issues which aren\u0027t worth fixing on a backport. I guess the hope is that people will upgrade.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"aee9ad15c960ccbd18d891a3e39d97cfc103edbc","unresolved":false,"context_lines":[{"line_number":112,"context_line":""},{"line_number":113,"context_line":"  This case should be rare. For many security situations the right answer"},{"line_number":114,"context_line":"  is to make the fix, make a new version, and strenuously suggest people"},{"line_number":115,"context_line":"  upgrade. The `OpenStack Vulnerability Management Team"},{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_69316f0b","line":115,"in_reply_to":"3a1ff146_a9b447f2","updated":"2017-03-15 14:42:52.000000000","message":"I\u0027m not a security person, but I\u0027d say that while there is a possibility to reach the vulnerable code (by providing older API version), the whole project is still vulnerable. What am I missing?","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":116,"context_line":"  \u003chttps://security.openstack.org/#vulnerability-management\u003e`_ has"},{"line_number":117,"context_line":"  the expertise to determine the true severity of a security bug."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"* A bug in the API service which results in a client getting a response"},{"line_number":120,"context_line":"  with a status code in the ``500-599`` range being fixed to return an"},{"line_number":121,"context_line":"  informative error response in the ``400-499`` range (when the"},{"line_number":122,"context_line":"  request was erroneous but fixable) or responding with success (when"},{"line_number":123,"context_line":"  the request was properly formed, but the server had broken"},{"line_number":124,"context_line":"  handling)."},{"line_number":125,"context_line":""},{"line_number":126,"context_line":"The following changes **do** require a version change:"},{"line_number":127,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_f4eff9ad","line":124,"range":{"start_line":119,"start_character":2,"end_line":124,"end_character":12},"updated":"2017-03-15 12:50:21.000000000","message":"+1 (this was a contentions point in past).","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":141,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":142,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":143,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":144,"context_line":"  require a version change."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"* Adding or removing a request or response header."},{"line_number":147,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_349a7115","line":144,"updated":"2017-03-15 12:50:21.000000000","message":"+1, I often see people doing things like `code \u003d\u003d 201` (I\u0027m looking at you, tempest!)","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"219030fa37cde8da36824ec304045ed13266241a","unresolved":false,"context_lines":[{"line_number":141,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":142,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":143,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":144,"context_line":"  require a version change."},{"line_number":145,"context_line":""},{"line_number":146,"context_line":"* Adding or removing a request or response header."},{"line_number":147,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_c95ece11","line":144,"in_reply_to":"3a1ff146_349a7115","updated":"2017-03-15 22:26:54.000000000","message":"hehe, nice point. And I am not sure Tempest is only guy to check the specific code.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3f89f3e777908a31dca8977767c9f6924f10bffe","unresolved":false,"context_lines":[{"line_number":149,"context_line":"  should be processed by the client. For example changing the value of the"},{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_74178951","line":153,"range":{"start_line":152,"start_character":0,"end_line":153,"end_character":24},"updated":"2017-03-15 12:50:21.000000000","message":"This is something I was referring to, when talking about drivers. If drivers have to expose something on API - you\u0027re out of luck here..","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"f908cc6f14217ca510ba1593d98ad0fa995f5e61","unresolved":false,"context_lines":[{"line_number":149,"context_line":"  should be processed by the client. For example changing the value of the"},{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_a3bb86c3","line":153,"range":{"start_line":152,"start_character":0,"end_line":153,"end_character":24},"in_reply_to":"3a1ff146_40fd6839","updated":"2017-03-15 13:58:53.000000000","message":"I don\u0027t think it\u0027s fine. Let\u0027s stop thinking about ironic and drivers. We have CRUD API /v1/foo, and every foo object has a JSON field. It is NOT a free-form field for users to populate as their desire (like our \"extra\" field). It\u0027s an actual API bit that heavily affects the operation of \"foo\" object. Should it be covered by versioning? I read this spec as \"YES OF COURSE\".","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"9343eceaf2306c31b13f8e3a2ee51244e86440b9","unresolved":false,"context_lines":[{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_704e8470","line":153,"in_reply_to":"3a1ff146_44abb574","updated":"2017-03-16 12:21:50.000000000","message":"leaky abstraction?\n\n(I\u0027m being deliberately naive here, reality is a lot more complex than some of this stuff seems to want to allow.)","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_fdd4a2ec","line":153,"in_reply_to":"3a1ff146_704e8470","updated":"2017-03-22 15:34:08.000000000","message":"Ironic API is extremely leaky, I don\u0027t disagree. Abstracting away so many features in so different hardware is probably hard to do perfect. I wonder if Nova has similar problems with different hypervisors..","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"33f3cff316e5164e4505aa9824396f265f964a62","unresolved":false,"context_lines":[{"line_number":149,"context_line":"  should be processed by the client. For example changing the value of the"},{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_40fd6839","line":153,"range":{"start_line":152,"start_character":0,"end_line":153,"end_character":24},"in_reply_to":"3a1ff146_74178951","updated":"2017-03-15 13:46:36.000000000","message":"@Dmitry, do you consider for example, fields in ironic\u0027s node.driver_info to be versioned by the rule of this spec? I didn\u0027t read it that way. As above, if it\u0027s documented as a json blob then I think it is fine here.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"d4e5fdc1f7c5bd97b309563b5341a62ecde8ab1f","unresolved":false,"context_lines":[{"line_number":149,"context_line":"  should be processed by the client. For example changing the value of the"},{"line_number":150,"context_line":"  ``Content-Type`` header to add a new media-type."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"* Adding or removing a property in a resource representation in either a"},{"line_number":153,"context_line":"  request or a response."},{"line_number":154,"context_line":""},{"line_number":155,"context_line":"* Changing the semantics or type of an existing property in a resource"},{"line_number":156,"context_line":"  representation (request or response)."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_44abb574","line":153,"range":{"start_line":152,"start_character":0,"end_line":153,"end_character":24},"in_reply_to":"3a1ff146_a3bb86c3","updated":"2017-03-15 15:53:05.000000000","message":"Okay, yes, I agree with you in that example. I also agree that\u0027s what e.g. node.driver_info should be like. However, we first need a schema (oh, and that will depend on the driver, and so I supposed you\u0027re right... hrm).","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"ef7d72c613028b55d4e2d5f83c54fc6bd5c840b3","unresolved":false,"context_lines":[{"line_number":231,"context_line":"References"},{"line_number":232,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"* Mailing list discussion, \"Standardizing status codes in the native API"},{"line_number":235,"context_line":"  (July 2012)\"."},{"line_number":236,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2012-July/thread.html#132"},{"line_number":237,"context_line":"* Mailing list discussion, \"refreshing and revalidating api compatibility"},{"line_number":238,"context_line":"  guidelines (January 2017)\"."},{"line_number":239,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2017-January/thread.html#110384"},{"line_number":240,"context_line":"* Blog posting, \"Interop API Requirements (February 2017)\"."},{"line_number":241,"context_line":"  https://blog.leafe.com/interop-api-requirements/"},{"line_number":242,"context_line":"* The review that created this document."},{"line_number":243,"context_line":"  https://review.openstack.org/#/c/421846/"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_5a8e3779","line":243,"range":{"start_line":234,"start_character":0,"end_line":243,"end_character":42},"updated":"2017-03-15 12:51:41.000000000","message":"can we have at least a single non-openstack reference? this problem is not new to us. has anyone widely known done anything similar?","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"129cb6108f2d293b65a133c7abceb40f91fbd4dc","unresolved":false,"context_lines":[{"line_number":231,"context_line":"References"},{"line_number":232,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"* Mailing list discussion, \"Standardizing status codes in the native API"},{"line_number":235,"context_line":"  (July 2012)\"."},{"line_number":236,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2012-July/thread.html#132"},{"line_number":237,"context_line":"* Mailing list discussion, \"refreshing and revalidating api compatibility"},{"line_number":238,"context_line":"  guidelines (January 2017)\"."},{"line_number":239,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2017-January/thread.html#110384"},{"line_number":240,"context_line":"* Blog posting, \"Interop API Requirements (February 2017)\"."},{"line_number":241,"context_line":"  https://blog.leafe.com/interop-api-requirements/"},{"line_number":242,"context_line":"* The review that created this document."},{"line_number":243,"context_line":"  https://review.openstack.org/#/c/421846/"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3a1ff146_daf85c7f","line":243,"range":{"start_line":234,"start_character":0,"end_line":243,"end_character":42},"in_reply_to":"3a1ff146_5a8e3779","updated":"2017-03-15 16:36:08.000000000","message":"Most APIs I\u0027m familiar with use SemVer, but that was deemed not suitable for some reason...likely because the frequency of non-backwards-compat changes is high enough that we\u0027d be bumping the major version a lot anyways.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"be845e1e7c22c0539f8ba0c990aad0be96f7ccb2","unresolved":false,"context_lines":[{"line_number":231,"context_line":"References"},{"line_number":232,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":233,"context_line":""},{"line_number":234,"context_line":"* Mailing list discussion, \"Standardizing status codes in the native API"},{"line_number":235,"context_line":"  (July 2012)\"."},{"line_number":236,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2012-July/thread.html#132"},{"line_number":237,"context_line":"* Mailing list discussion, \"refreshing and revalidating api compatibility"},{"line_number":238,"context_line":"  guidelines (January 2017)\"."},{"line_number":239,"context_line":"  http://lists.openstack.org/pipermail/openstack-dev/2017-January/thread.html#110384"},{"line_number":240,"context_line":"* Blog posting, \"Interop API Requirements (February 2017)\"."},{"line_number":241,"context_line":"  https://blog.leafe.com/interop-api-requirements/"},{"line_number":242,"context_line":"* The review that created this document."},{"line_number":243,"context_line":"  https://review.openstack.org/#/c/421846/"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a1ced50_7d15129a","line":243,"range":{"start_line":234,"start_character":0,"end_line":243,"end_character":42},"in_reply_to":"3a1ff146_daf85c7f","updated":"2017-03-22 15:34:08.000000000","message":"\u003e we\u0027d be bumping the major version a lot anyways\n\nWhat is wrong about that though? Firefox bumps major version every release :)\n\nI\u0027d prefer us using SemVer, but it seems a lost battle.","commit_id":"e8e1af2a34e6c52eb14f6edfea744dba2e545260"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"eea5a38755c9e6434b551e64f4da372aabecf55f","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_13e08a95","line":261,"updated":"2017-03-22 17:45:17.000000000","message":"So, it seems weird to put in a really minimally worked example of an alternative. I think the guideline should really be \"here is what we suggest.\"\n\nI am concerned with this in here because it becomes like the YAML/TOML issue in python. \"The YAML spec is \u003e 200 pages, so we should pick a new markup\". Old specs are long because they worked through all the real world issues.\n\nSo as people look through this, say, this is complicated, then decide \"well I\u0027m doing the alternative suggested instead.\"","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"af9ebf2c56787ace2e46f099004d2b860a2eb39b","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_eb94b337","line":261,"updated":"2017-03-23 11:57:52.000000000","message":"So, the \"stable\" means \"when a resolurce is put into this API it will not change\" e.g. - in the example I used for the Zebra as a Service when the zebra resource was moved into the API, the methods, and data structure of the resource (in this case the zebra)  will not change.\n\nI would be horrified if people ended up with /zaas/v1/real_zebra , /zaas/v1/real_zebra_with_unicorn_option etc.\n\nSure, this means that API changes will have to be more complete before exposing them to users as stable, but it should reduce the amount of churn you get on API resources, if we know we cannot change them in the future.\n\nSupporting microversions is a lot more then checking for the existance of a feature - as data structures can change between versions, the client code needs to know who to change the data it has in its store, and how to change the data in the responce to match what it needs.\n\ndoing (for example) \n\nOPTIONS /zaas/v1/zebra HTTP/1.1\n\nand getting back a 404 or a 200 is infintely easier than getting the list of microversions, looking up the required one in the clients *hardcoded* copy of the ZaaS API history, lookig at the request to see if there are any features requiring some other special microversion (e.g. paint\u003dFalse in the example) mangling the data to match the common micorversion that the client and the server support, sending the request, taking back the data, mangling the data back to the clients internal data structure and passing it back to what ever called the client tool.\n\nThe point is, if you want to rapid constant change to your API microversions might work (if clients and libraries actually implment the support, and dont just use the default and hope for the best, or just hardcode a microversion header to get that one feature), but if your project is commited to plan out its API, and work around API issues internally - that is a pretty good choice too.","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"59c157ab5ba8b2aa58d57700291a1a1134fffded","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_bcdb037b","line":261,"in_reply_to":"1a1ced50_01ed94b6","updated":"2017-03-22 18:36:01.000000000","message":"Assume you have a \"stable API\".  Now you add a new feature that requires changing it, so you add a new version of that \"stable API\" on a new endpoint/URL.  Rinse and repeat, and soon you have 6 versions of the \"same\" API, all differing slightly from each other.  (This happened to the Linux kernel, for example.)\n\nNow do the same thing for a bunch of other APIs within a project (nova for example), and soon you have multiple different \"stable\" URLs for each feature, and the client still needs to figure out which one to use.  And the only way to simplify the server side code is to eventually drop some of the \"stable\" URLs, which will break any clients using them.\n\nHow is this fundamentally different from having 30 microversions, and eventually wanting to raise the minimum version?","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"5c4642c21d48d35d979ebacf6297bc8553cae71b","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_01ed94b6","line":261,"in_reply_to":"1a1ced50_13e08a95","updated":"2017-03-22 18:24:55.000000000","message":"Well, yes - and my point is it is overly complex.\n\nWe should at least acknowledge that the micro version solution is complex at best, and that \"real world issues\" have not been fully worked out yet (and will not be until we do the first min_version raise).\n\nFrom my perspective, I would not argue against projects following this guideline based on it being too complex, I would do it on the basis that we should not export our compatibility problems to our users, rather try and internalize them, while keeping the same API.\n\nFrom an actual \"API Stability\" point, the alternative here is a better solution.","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"f7d373b075e06fe65fe576f19b04d4143513295e","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_96a7080a","line":261,"in_reply_to":"1a1ced50_13e08a95","updated":"2017-03-22 17:55:31.000000000","message":"good point","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"},{"author":{"_account_id":8768,"name":"Chris Friesen","email":"chris.friesen@windriver.com","username":"cbf123"},"change_message_id":"16e14731fad369f651ef6fbcaabd81fad20f5b59","unresolved":false,"context_lines":[{"line_number":258,"context_line":"This course of action is not recommended by the API Working Group. As stated"},{"line_number":259,"context_line":"before the overarching goal of the group is to encourage consistency in the"},{"line_number":260,"context_line":"APIs of all the services. The idea is presented here solely for illustrative"},{"line_number":261,"context_line":"purposes."},{"line_number":262,"context_line":""},{"line_number":263,"context_line":"References"},{"line_number":264,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a1ced50_8935fda9","line":261,"in_reply_to":"1a1ced50_eb94b337","updated":"2017-03-23 15:54:37.000000000","message":"No matter how well you plan, there will be a need for modifying supposedly stable APIs.  I worked in kernel development for a decade.  They commit to permanently supporting each syscall, so they try really hard to get it right the first time.  And they still ended up with six variations of pselect(), four variations of wait(), three variations of dup(), etc.\n\nJust as a hypothetical, consider nova\u0027s live migration API.  Initially it required the user to explicitly specify whether it was a block migration or not.  Then someone said \"hey, nova can figure that out on its own in most cases already, let\u0027s make that option so it\u0027s simpler for the end-user\".  Then someone said \"hey, we should really allow bypassing the scheduler when migrating in case we really *need* to force a migration to a specific host even if it violates scheduler filters\".  Then someone said \"hey, these pre-checks are taking way too long, we should make them async rather than sync so that migrations can succeed rather than fail due to timeout\".  And now people are saying \"hey, maybe we should allow specifying the timeout per-migration rather than per compute node, and we should let the admin determine per-migration what the action should be if it times out\".\n\nAll the above happened incrementally over multiple years, and some of the pieces depended on functionality that became available in other parts of the system over time.  It would be unrealistic to expect people to come up with the final solution up-front.","commit_id":"d9af76aa244b8704cdff8f436b4b8882e3af1e99"}],"guidelines/api_interoperability.rst":[{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3874bd45002dd54a03fcb31891830cfd59a144ab","unresolved":false,"context_lines":[{"line_number":31,"context_line":"            the availability of different drivers present significant"},{"line_number":32,"context_line":"            challenges for interoperability. Where possible such differences"},{"line_number":33,"context_line":"            should be avoided. Where that\u0027s not possible, interoperability"},{"line_number":34,"context_line":"            should be considered when cloud `A` and cloud `B` have the same"},{"line_number":35,"context_line":"            driver available."},{"line_number":36,"context_line":""},{"line_number":37,"context_line":"* Version discovery and selection should default to a baseline; making use of"},{"line_number":38,"context_line":"  new features and changes in an API should be opt-in."}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_6fc5165b","line":35,"range":{"start_line":34,"start_character":68,"end_line":35,"end_character":28},"updated":"2017-04-07 16:16:47.000000000","message":"nit: \"the same sets of drivers available and enabled\". mmm, and maybe \"the same versions of the same drivers\". tl;dr in this case it\u0027s probably not possible.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f1d1554211b037794c8c3a4ad65bc62bd3e83269","unresolved":false,"context_lines":[{"line_number":82,"context_line":""},{"line_number":83,"context_line":".. note:: A project which does not have a robust system for managing version"},{"line_number":84,"context_line":"          boundaries but must make changes to their API is by definition not"},{"line_number":85,"context_line":"          adhering to these guidelines for interoperability The project itself"},{"line_number":86,"context_line":"          must make the decisions on how to evolve their API. If this leads to"},{"line_number":87,"context_line":"          conflicts with other projects within the OpenStack ecosystem, the"},{"line_number":88,"context_line":"          role of the API-WG is solely to help clarify the guidelines and"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_ec303beb","line":85,"updated":"2017-04-06 19:58:46.000000000","message":"sigh: missing \u0027.\u0027 before The","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"e4d6ddfd913070ca8cfff6d4f3c50c5b06545841","unresolved":false,"context_lines":[{"line_number":88,"context_line":"          role of the API-WG is solely to help clarify the guidelines and"},{"line_number":89,"context_line":"          provide advice on how to minimize the impact of changes. The"},{"line_number":90,"context_line":"          Technical Committee is the body which provides adjudication and"},{"line_number":91,"context_line":"          mediation when consensus cannot be reached."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"Whether a service follows the guidelines or not, any service should always"},{"line_number":94,"context_line":"strive to minimize API changes and version increases as that exacerbates the"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_8114d84f","line":91,"updated":"2017-04-06 19:56:24.000000000","message":"i like this wording","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3874bd45002dd54a03fcb31891830cfd59a144ab","unresolved":false,"context_lines":[{"line_number":88,"context_line":"          role of the API-WG is solely to help clarify the guidelines and"},{"line_number":89,"context_line":"          provide advice on how to minimize the impact of changes. The"},{"line_number":90,"context_line":"          Technical Committee is the body which provides adjudication and"},{"line_number":91,"context_line":"          mediation when consensus cannot be reached."},{"line_number":92,"context_line":""},{"line_number":93,"context_line":"Whether a service follows the guidelines or not, any service should always"},{"line_number":94,"context_line":"strive to minimize API changes and version increases as that exacerbates the"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_8fc61a48","line":91,"in_reply_to":"bff0334d_8114d84f","updated":"2017-04-07 16:16:47.000000000","message":"+1","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3874bd45002dd54a03fcb31891830cfd59a144ab","unresolved":false,"context_lines":[{"line_number":107,"context_line":"are given fairly narrow definitions:"},{"line_number":108,"context_line":""},{"line_number":109,"context_line":"**compatibility**"},{"line_number":110,"context_line":"  An API is compatible when client code written for that service on cloud"},{"line_number":111,"context_line":"  `A` will work without changes with the same service on cloud `B`."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"**stability**"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_0f368a53","line":110,"updated":"2017-04-07 16:16:47.000000000","message":"I think it\u0027s important to write \"any client code\". this requirement is easy to fulfil for https://martinfowler.com/bliki/TolerantReader.html.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"5f8ef53d0309bc9f0684568e71fbcdc89a932245","unresolved":false,"context_lines":[{"line_number":107,"context_line":"are given fairly narrow definitions:"},{"line_number":108,"context_line":""},{"line_number":109,"context_line":"**compatibility**"},{"line_number":110,"context_line":"  An API is compatible when client code written for that service on cloud"},{"line_number":111,"context_line":"  `A` will work without changes with the same service on cloud `B`."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"**stability**"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_b94e7a6c","line":110,"in_reply_to":"bff0334d_0f368a53","updated":"2017-04-11 10:27:26.000000000","message":"Is your suggestion to add \"any\"?\n\nIf so, I left that out in both of these definitions because it is redundant and I wanted the definitions to be crisp and short.\n\nIf some client code is written, for cloud A, then it is exists, is a member of \"any\" and needs to work on cloud B for A and B to compatible.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"e45288fc28f513f16ca8fd9cd8f2c5ec7c8ec5e1","unresolved":false,"context_lines":[{"line_number":107,"context_line":"are given fairly narrow definitions:"},{"line_number":108,"context_line":""},{"line_number":109,"context_line":"**compatibility**"},{"line_number":110,"context_line":"  An API is compatible when client code written for that service on cloud"},{"line_number":111,"context_line":"  `A` will work without changes with the same service on cloud `B`."},{"line_number":112,"context_line":""},{"line_number":113,"context_line":"**stability**"}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_59a76e0c","line":110,"in_reply_to":"bff0334d_b94e7a6c","updated":"2017-04-11 10:32:00.000000000","message":"My comment is to clarify how much sanity we expect of the client for this definition to apply. This proposal assumes none, but it\u0027s common to assume that client does not do unfortunate things.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"3874bd45002dd54a03fcb31891830cfd59a144ab","unresolved":false,"context_lines":[{"line_number":156,"context_line":"  There continues to be some lingering debate on this topic with regard to"},{"line_number":157,"context_line":"  changing success codes. A robust client (see below) could effectively ride"},{"line_number":158,"context_line":"  through changes in success if it treated anything from ``200`` to ``299`` as"},{"line_number":159,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":160,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":161,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":162,"context_line":"  require a version change."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* Adding or removing a request or response header."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_0f5d6a79","line":162,"range":{"start_line":159,"start_character":11,"end_line":162,"end_character":27},"updated":"2017-04-07 16:16:47.000000000","message":"I\u0027d not make this guideline depend on how well the documentation is written. This gets back to assuming a Tolerant Reader, which we (nearly explicitly) agreed NOT to assume.\n\nThis is my main -1 point.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"5f8ef53d0309bc9f0684568e71fbcdc89a932245","unresolved":false,"context_lines":[{"line_number":159,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":160,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":161,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":162,"context_line":"  require a version change."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* Adding or removing a request or response header."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_3e0ff037","line":162,"in_reply_to":"bff0334d_0f5d6a79","updated":"2017-04-11 10:27:26.000000000","message":"I\u0027m not entirely certain how to address this. Are you suggesting the entire paragraph be removed?\n\nYour comment does point out that if it stays the \"see below\" needs to be removed, because the thing that was below was removed.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"e45288fc28f513f16ca8fd9cd8f2c5ec7c8ec5e1","unresolved":false,"context_lines":[{"line_number":159,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":160,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":161,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":162,"context_line":"  require a version change."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* Adding or removing a request or response header."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_d98b7e65","line":162,"in_reply_to":"bff0334d_3e0ff037","updated":"2017-04-11 10:32:00.000000000","message":"I\u0027d change it (in spirit of what we discuss above) to something like \"This only works, however, if the way clients are written match our assumptions on how HTTP clients should be written.\" To emphasize the (important, I think) point of this spec that stability requires nearly no assumptions about the client, except for following the HTTP standard. Please let me know if it makes sense.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"aa35b73835d7b635b48ec812ed00e6dc1c745099","unresolved":false,"context_lines":[{"line_number":159,"context_line":"  success. This only works, however, if the service documentation has"},{"line_number":160,"context_line":"  explicitly stated that the broad definition of success should be used. If it"},{"line_number":161,"context_line":"  states a specific response code as success, then changing that code would"},{"line_number":162,"context_line":"  require a version change."},{"line_number":163,"context_line":""},{"line_number":164,"context_line":"* Adding or removing a request or response header."},{"line_number":165,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"bff0334d_19b0c689","line":162,"in_reply_to":"bff0334d_d98b7e65","updated":"2017-04-11 10:52:34.000000000","message":"What you say makes sense, but we aren\u0027t making the assumption that client code is written to a high standard. We\u0027re assuming that it worked once, in normal circumstances, thus should continue working.\n\nI\u0027ll make some adjustments.","commit_id":"386a4e6f8e01cfdaf61437d8b166df2afe2029c0"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"0fab1a5de7fac2b6aeb5bdb02607a76e0b9d53ea","unresolved":false,"context_lines":[{"line_number":11,"context_line":"The OpenStack mission includes the following goal for OpenStack clouds:"},{"line_number":12,"context_line":"\"interoperable between deployments\". In the context of HTTP APIs this means"},{"line_number":13,"context_line":"that client code that is written for cloud `A` should also work on cloud"},{"line_number":14,"context_line":"`B` and any other cloud. Because cloud `A` and cloud `B` may be running"},{"line_number":15,"context_line":"different releases of the OpenStack services at any given point in time,"},{"line_number":16,"context_line":"and they may upgrade their services at different points in time, this has"},{"line_number":17,"context_line":"important implications for how API developers add features, fix bugs, and"}],"source_content_type":"text/x-rst","patch_set":11,"id":"5ff73747_832e1441","line":14,"range":{"start_line":14,"start_character":18,"end_line":14,"end_character":23},"updated":"2017-04-25 17:45:46.000000000","message":"nit: s/cloud/clouds/","commit_id":"4449bcd4e54968ab0239c9f7c100b780524300b5"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"0fab1a5de7fac2b6aeb5bdb02607a76e0b9d53ea","unresolved":false,"context_lines":[{"line_number":42,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":43,"context_line":"  violated. When a service uses microversions, \"major version update\" often"},{"line_number":44,"context_line":"  means raising the minimum available version, signalled by the"},{"line_number":45,"context_line":"  ``next_min_version`` field."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":48,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":11,"id":"5ff73747_a34350af","line":45,"range":{"start_line":45,"start_character":4,"end_line":45,"end_character":20},"updated":"2017-04-25 17:45:46.000000000","message":"I could not find this next_min_version on current microversion spec. It would be nice to add this later on the spec also.","commit_id":"4449bcd4e54968ab0239c9f7c100b780524300b5"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"9e1cb7d7ef8f14267b840ef469afea980ec06872","unresolved":false,"context_lines":[{"line_number":42,"context_line":"  version update because stability (backwards compatibility) has been"},{"line_number":43,"context_line":"  violated. When a service uses microversions, \"major version update\" often"},{"line_number":44,"context_line":"  means raising the minimum available version, signalled by the"},{"line_number":45,"context_line":"  ``next_min_version`` field."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"* If functionality is going to be removed its removal should follow"},{"line_number":48,"context_line":"  standard OpenStack deprecation procedures."}],"source_content_type":"text/x-rst","patch_set":11,"id":"5ff73747_fd2acc29","line":45,"range":{"start_line":45,"start_character":4,"end_line":45,"end_character":20},"in_reply_to":"5ff73747_a34350af","updated":"2017-04-27 14:27:23.000000000","message":"It is a proposed change: https://review.openstack.org/#/c/446138/\n\nI\u0027m wondering if merging this language means that we are de facto approving that other change.","commit_id":"4449bcd4e54968ab0239c9f7c100b780524300b5"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"f4e9c2c34cf30370c3947e21a5004c68eacee349","unresolved":false,"context_lines":[{"line_number":243,"context_line":"defined here) too early in its development. Only once some form of stability"},{"line_number":244,"context_line":"(in the standard English sense) has been reached is it worth considering."},{"line_number":245,"context_line":""},{"line_number":246,"context_line":"A project which has an existing stable service that wants to experiment with"},{"line_number":247,"context_line":"new functionality that it may choose to never stabilize should publish that"},{"line_number":248,"context_line":"experimental service at a unique endpoint in the service catalog, separate"},{"line_number":249,"context_line":"from the existing service."},{"line_number":250,"context_line":""},{"line_number":251,"context_line":".. _tolerant reader: https://martinfowler.com/bliki/TolerantReader.html"},{"line_number":252,"context_line":""}],"source_content_type":"text/x-rst","patch_set":11,"id":"5ff73747_06c5c08e","line":249,"range":{"start_line":246,"start_character":0,"end_line":249,"end_character":26},"updated":"2017-04-22 00:44:31.000000000","message":"+100","commit_id":"4449bcd4e54968ab0239c9f7c100b780524300b5"}]}