)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":2889,"name":"Aeva Black","email":"aeva.online@gmail.com","username":"tenbrae"},"change_message_id":"0118c81d7d0cde077f667563be78cda348e58ee8","unresolved":false,"context_lines":[{"line_number":3,"context_line":"AuthorDate: 2015-02-12 19:09:48 -0800"},{"line_number":4,"context_line":"Commit:     Miguel Grinberg \u003cmiguelgrinberg50@gmail.com\u003e"},{"line_number":5,"context_line":"CommitDate: 2015-03-26 15:15:17 -0700"},{"line_number":6,"context_line":""},{"line_number":7,"context_line":"tagging guidelines"},{"line_number":8,"context_line":""},{"line_number":9,"context_line":"Change-Id: I53e11690ed04d46d4dcd089267b0fd9bee729692"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":7,"id":"dac4157f_c62fecf4","line":6,"updated":"2015-04-21 21:21:51.000000000","message":"this commit message is very short and not descriptive. Many projects have a policy of including a summary of the spec in the commit message (sometimes just the first para or two). I think that\u0027s appropriate and would be helpful here as well.","commit_id":"649db146c1a1481e5ed488766e816cb1fe8d444d"}],"guidelines/tags.rst":[{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Tags Representation"},{"line_number":13,"context_line":"-------------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"Tags are simple strings that can be attached to an entity with the purpose of"},{"line_number":16,"context_line":"classification into groups. An entity can have zero, one or more tags"},{"line_number":17,"context_line":"associated with it, for that reason the recommended representation within the"},{"line_number":18,"context_line":"parent entity is as a list."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_776bb3f1","line":15,"updated":"2015-02-13 15:35:48.000000000","message":"Wording nit: \"Tags are strings attached to an entity\" seems a bit cleaner.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"9c7e7d1a2bacb8cf995053c9cde76d988a8c5a15","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Tags Representation"},{"line_number":13,"context_line":"-------------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"Tags are simple strings that can be attached to an entity with the purpose of"},{"line_number":16,"context_line":"classification into groups. An entity can have zero, one or more tags"},{"line_number":17,"context_line":"associated with it, for that reason the recommended representation within the"},{"line_number":18,"context_line":"parent entity is as a list."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_ed790ffd","line":15,"in_reply_to":"da86d52c_776bb3f1","updated":"2015-02-18 04:05:27.000000000","message":"Done","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"8abce7d5f4c9ff3f877b4cff2a0e7e890411e4dc","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Tags Representation"},{"line_number":13,"context_line":"-------------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"Tags are simple strings that can be attached to an entity with the purpose of"},{"line_number":16,"context_line":"classification into groups. An entity can have zero, one or more tags"},{"line_number":17,"context_line":"associated with it, for that reason the recommended representation within the"},{"line_number":18,"context_line":"parent entity is as a list."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_e55b5b53","line":15,"in_reply_to":"da86d52c_776bb3f1","updated":"2015-02-13 21:51:40.000000000","message":"IIRC, the nova tags spec review had a lot of discussion (and confusion) about the fact that the tags were meant to be \"simple strings\" -- which I\u0027m guessing is where you are coming from here.\n\nDid you considering adding some text to differentiate between tags and metadata?  I think that there may be helpful to explain the differences and why once would be chosen over the over.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"253f61768eddfb293e8f0145362188e53102f925","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Tags Representation"},{"line_number":13,"context_line":"-------------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"Tags are simple strings that can be attached to an entity with the purpose of"},{"line_number":16,"context_line":"classification into groups. An entity can have zero, one or more tags"},{"line_number":17,"context_line":"associated with it, for that reason the recommended representation within the"},{"line_number":18,"context_line":"parent entity is as a list."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_45c98678","line":15,"in_reply_to":"da86d52c_e55b5b53","updated":"2015-02-13 22:09:09.000000000","message":"Sure, I will add a sentence to differentiate tags from metadata.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":72,"context_line":"Note that this representation differs from the one adopted by Nova. One reason"},{"line_number":73,"context_line":"is that with this structure it is possible to add additional metadata to the"},{"line_number":74,"context_line":"request body. A secondary reason is that JSON arrays as a top level entity"},{"line_number":75,"context_line":"have been found to expose vulnerabilities in browsers, as reported by the"},{"line_number":76,"context_line":"following articles:"},{"line_number":77,"context_line":""},{"line_number":78,"context_line":"- http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_d71fff6e","line":75,"updated":"2015-02-13 15:35:48.000000000","message":"Thank you for mentioning this about top-level lists.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"ad6c8da356cee92767619ba4856d64d9ab72a37f","unresolved":false,"context_lines":[{"line_number":72,"context_line":"Note that this representation differs from the one adopted by Nova. One reason"},{"line_number":73,"context_line":"is that with this structure it is possible to add additional metadata to the"},{"line_number":74,"context_line":"request body. A secondary reason is that JSON arrays as a top level entity"},{"line_number":75,"context_line":"have been found to expose vulnerabilities in browsers, as reported by the"},{"line_number":76,"context_line":"following articles:"},{"line_number":77,"context_line":""},{"line_number":78,"context_line":"- http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_94a1bc97","line":75,"updated":"2015-02-16 19:02:17.000000000","message":"This also complies with guidelines on collections elsewhere in the api-wg corpus...","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"8abce7d5f4c9ff3f877b4cff2a0e7e890411e4dc","unresolved":false,"context_lines":[{"line_number":82,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":83,"context_line":""},{"line_number":84,"context_line":"To add, remove, or change tags, a PUT request should be sent to the"},{"line_number":85,"context_line":"root tags URL, with the updated complete list of tagsin the\tbody of the"},{"line_number":86,"context_line":"request. On success, the server responds with a 200 status code and the"},{"line_number":87,"context_line":"complete updated tag list in the response body."},{"line_number":88,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_65868b18","line":85,"updated":"2015-02-13 21:51:40.000000000","message":"s/tagsin/\"tags in\" and the » character","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"9c7e7d1a2bacb8cf995053c9cde76d988a8c5a15","unresolved":false,"context_lines":[{"line_number":82,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":83,"context_line":""},{"line_number":84,"context_line":"To add, remove, or change tags, a PUT request should be sent to the"},{"line_number":85,"context_line":"root tags URL, with the updated complete list of tagsin the\tbody of the"},{"line_number":86,"context_line":"request. On success, the server responds with a 200 status code and the"},{"line_number":87,"context_line":"complete updated tag list in the response body."},{"line_number":88,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_2d8087be","line":85,"in_reply_to":"da86d52c_65868b18","updated":"2015-02-18 04:05:27.000000000","message":"Done","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":117,"context_line":"endpoints to give clients the ability to work with individual tags. Each tag"},{"line_number":118,"context_line":"can be accessed individually by appending the tag name to the root tag URL."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"To insert a single tag without having to send the entire tag list, the client"},{"line_number":121,"context_line":"should send a PUT request to the inidividual tag URL. On success, the server"},{"line_number":122,"context_line":"responds with a 201 status code and includes the new tag\u0027s URL in the"},{"line_number":123,"context_line":"``Location`` header in the response."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_ba126f07","line":120,"updated":"2015-02-13 15:35:48.000000000","message":"Why not allow PATCH so you can send N new tags without sending the full list?","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"ecbfc2d79e0b879c93f0d0ded7e2182a1c42faa8","unresolved":false,"context_lines":[{"line_number":117,"context_line":"endpoints to give clients the ability to work with individual tags. Each tag"},{"line_number":118,"context_line":"can be accessed individually by appending the tag name to the root tag URL."},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"To insert a single tag without having to send the entire tag list, the client"},{"line_number":121,"context_line":"should send a PUT request to the inidividual tag URL. On success, the server"},{"line_number":122,"context_line":"responds with a 201 status code and includes the new tag\u0027s URL in the"},{"line_number":123,"context_line":"``Location`` header in the response."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_83161f57","line":120,"in_reply_to":"da86d52c_ba126f07","updated":"2015-02-13 18:42:15.000000000","message":"I don\u0027t know. PATCH is set to a resource to make a partial change. But here we are using individual resources for each tag, so really when you have a /.../tags/\u003ctag-name\u003e URL this is a complete resource.\n\nAn alternative to this would be to not use individual tag URLs, then a PATCH to the /.../tags resource can do a partial update.\n\nI prefer the former, to be honest. I\u0027m not too big on PATCH, the semantics of it are not well defined in my opinion. For example, it seems straightforward to add a tag, but how do you remove one?","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":138,"context_line":""},{"line_number":139,"context_line":"To delete a single tag without affecting the remaining ones, a"},{"line_number":140,"context_line":"DELETE request is sent to the individual tag URL. On success, the server"},{"line_number":141,"context_line":"responds with a 204 status code."},{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_7729f288","line":141,"updated":"2015-02-13 15:35:48.000000000","message":"If a tag doesn\u0027t exist and is DELETEd will the return also be 404?","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"ecbfc2d79e0b879c93f0d0ded7e2182a1c42faa8","unresolved":false,"context_lines":[{"line_number":138,"context_line":""},{"line_number":139,"context_line":"To delete a single tag without affecting the remaining ones, a"},{"line_number":140,"context_line":"DELETE request is sent to the individual tag URL. On success, the server"},{"line_number":141,"context_line":"responds with a 204 status code."},{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_2307331f","line":141,"in_reply_to":"da86d52c_7729f288","updated":"2015-02-13 18:42:15.000000000","message":"Correct. Will update the doc to state that.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"    DELETE /servers/1234567890/tags/qux"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Filtering and Searching by Tags"},{"line_number":148,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_5aced3b8","line":145,"updated":"2015-02-13 15:35:48.000000000","message":"Does deleting multiple tags require multiple requests, or can they be merged with something like:\n\nDELETE /servers/1234567890/tags/bar,qux\n\nThis could be a good use case for PATCH, so a JSON body with multiple add/remove ops could be sent to do multiple transformations in one request.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"ecbfc2d79e0b879c93f0d0ded7e2182a1c42faa8","unresolved":false,"context_lines":[{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"    DELETE /servers/1234567890/tags/qux"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Filtering and Searching by Tags"},{"line_number":148,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_76800b4a","line":145,"in_reply_to":"da86d52c_5aced3b8","updated":"2015-02-13 18:42:15.000000000","message":"DELETE used in this way can be used with a single tag. This follows the idea that tags are seen as stand-alone resources.\n\nHere you hint at my main issue with PATCH. The problem is that you cannot use the resource representation, you have to invent a meta-representation that defines what changes to make to the resource. For example, you need an operation (i.e. add, remove, etc.). So the body of the PATCH request does not have a resource representation, it has something else. It gets uglier if the API supports multiple content-types for resource representations, now you have to define these meta-representations for PATCH in JSON, XML, etc.\n\nI think you avoid a lot of complexity but enforcing the rule that the only thing that travels in the body of requests and responses are resource representations.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"2bb097479aa5d970a048d4319802b2f01fd2b65e","unresolved":false,"context_lines":[{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"    DELETE /servers/1234567890/tags/qux"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Filtering and Searching by Tags"},{"line_number":148,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_c83aeb97","line":145,"in_reply_to":"da86d52c_76800b4a","updated":"2015-02-13 22:30:52.000000000","message":"Hrm, a meta-representation would be needed (as you say) but I think it would be worth the effort. I can be persuaded, but I would love to hear how others feel about it first.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"ad6c8da356cee92767619ba4856d64d9ab72a37f","unresolved":false,"context_lines":[{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"    DELETE /servers/1234567890/tags/qux"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Filtering and Searching by Tags"},{"line_number":148,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_f470380a","line":145,"in_reply_to":"da86d52c_c83aeb97","updated":"2015-02-16 19:02:17.000000000","message":"If you want to delete a bunch of tags, the right thing is to PUT a new list to .../tags.\n\nThat is: you are PUTting a new representation of the tags list to the resource that represents the tags list.\n\nMaking a meta resource that represents some, but not all, tags is asking for trouble down the road as it opens the mind to being sloppy with resource design for the sake of small conveniences.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"9b6fea28196b6a04a2b77ef6cfba1ed7c37648b4","unresolved":false,"context_lines":[{"line_number":142,"context_line":""},{"line_number":143,"context_line":"Example request::"},{"line_number":144,"context_line":""},{"line_number":145,"context_line":"    DELETE /servers/1234567890/tags/qux"},{"line_number":146,"context_line":""},{"line_number":147,"context_line":"Filtering and Searching by Tags"},{"line_number":148,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_2b142ae8","line":145,"in_reply_to":"da86d52c_f470380a","updated":"2015-02-16 19:41:04.000000000","message":"Very valid, I didn\u0027t consider PUTing as a way to do that. Sounds cleaner than adding a PATCH implementation.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":152,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":153,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":154,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":155,"context_line":"``tags-any``, ``not-tags`` and ``not-tags-any``."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_378e9ad1","line":155,"updated":"2015-02-13 15:35:48.000000000","message":"I think it would be more human-friendly to make the arguments:\n\n- any-tags\n- not-tags\n- not-any-tags\n- any-not-tags (where the latter two are equivalent) \n\nSaying \"not-tags-any\" sounds stilted to me (though the boolean mathematician in me is pleased) from a UX perspective.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"9c7e7d1a2bacb8cf995053c9cde76d988a8c5a15","unresolved":false,"context_lines":[{"line_number":152,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":153,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":154,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":155,"context_line":"``tags-any``, ``not-tags`` and ``not-tags-any``."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_8d517364","line":155,"in_reply_to":"da86d52c_19ab801f","updated":"2015-02-18 04:05:27.000000000","message":"I did not change these names yet. I really see no benefit, plus the \"tags-any\" name is already in use by nova, so given that it is just a minor name change it does not seem worth changing.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"2bb097479aa5d970a048d4319802b2f01fd2b65e","unresolved":false,"context_lines":[{"line_number":152,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":153,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":154,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":155,"context_line":"``tags-any``, ``not-tags`` and ``not-tags-any``."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_19ab801f","line":155,"in_reply_to":"da86d52c_360133b0","updated":"2015-02-13 22:30:52.000000000","message":"Of course, I didn\u0027t mean to propose getting rid of \"tags\". Your reply is exactly what I actually meant.\n\nI still like having a \"any-not-tags\" synonym for \"not-any-tags\" to ease users\u0027 memory burden, but it\u0027s not vital.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"ecbfc2d79e0b879c93f0d0ded7e2182a1c42faa8","unresolved":false,"context_lines":[{"line_number":152,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":153,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":154,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":155,"context_line":"``tags-any``, ``not-tags`` and ``not-tags-any``."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_360133b0","line":155,"in_reply_to":"da86d52c_378e9ad1","updated":"2015-02-13 18:42:15.000000000","message":"I need to think about this to make sure we can cover all the cases with your suggested names. The tags and tags-any are based on the nova spec, the not-tags is my own addition to cover the negative filtering.\n\nYour \"any-tags\" covers the \"or\" operator, but we need another argument to specify the \"and\". In my proposal this is done by \"tags\".\n\nThe two negative filters in my proposal are also different, they represent the  \"and\" and the \"or\" in their negative form.\n\nIt seems you are short on some of these. How about:\n\n- tags: must have all tags given\n- not-tags: must not have all tags given\n- any-tags: must have at least one tag given\n- not-any-tags: must not have at least one tag given","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"8abce7d5f4c9ff3f877b4cff2a0e7e890411e4dc","unresolved":false,"context_lines":[{"line_number":156,"context_line":""},{"line_number":157,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":159,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":160,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":161,"context_line":"not having good support among web clients and servers."},{"line_number":162,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_05f30fa0","line":159,"updated":"2015-02-13 21:51:40.000000000","message":"+1","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6bb488dac76408cacb714273d0b858afa53b6dec","unresolved":false,"context_lines":[{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":159,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":160,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":161,"context_line":"not having good support among web clients and servers."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":164,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_684f086b","line":161,"updated":"2015-02-16 19:06:23.000000000","message":"This is unfortunate because now we must ask the question:\n\n    How do I indicate a tag with a \u0027,\u0027 in it?\n\nIf we did allow multiple query parameters with the same name the question goes away.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"9c7e7d1a2bacb8cf995053c9cde76d988a8c5a15","unresolved":false,"context_lines":[{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":159,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":160,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":161,"context_line":"not having good support among web clients and servers."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":164,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_6ddb5fed","line":161,"in_reply_to":"da86d52c_0b4a0655","updated":"2015-02-18 04:05:27.000000000","message":"I went with (a) here. I don\u0027t think urlencoding is a good idea, at the level where the URL is going to be looked at it would be already urldecoded. It\u0027s either escaping somehow (maybe two commas?) or not allowing the comma. I prefer not allowing commas.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"9b6fea28196b6a04a2b77ef6cfba1ed7c37648b4","unresolved":false,"context_lines":[{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":159,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":160,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":161,"context_line":"not having good support among web clients and servers."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":164,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_0b4a0655","line":161,"in_reply_to":"da86d52c_684f086b","updated":"2015-02-16 19:41:04.000000000","message":"Unfortunately there are some servers and clients that don\u0027t work with multiple identically named parameters. For example, any HTTP client that represents parameters as a dictionary/hashmap. The options for handling literal commas in tags I can see are:\n\na) Simply disallowed (annoying)\n\nb) Solved server-side with a longest-match strategy (complex)\n\nc) Resolved by encoding literal commas as %2C (still annoying)\n\nMy preferred solution would be (c) though it\u0027s only the best of a bad batch. Other solutions are very welcome, I\u0027d really like not to restrict tag content too much.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"ff4bc74f0851e4c2248df94b95d58bcca5a61dbd","unresolved":false,"context_lines":[{"line_number":158,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":159,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":160,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":161,"context_line":"not having good support among web clients and servers."},{"line_number":162,"context_line":""},{"line_number":163,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":164,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_9bdeff3c","line":161,"in_reply_to":"da86d52c_6ddb5fed","updated":"2015-02-18 13:07:09.000000000","message":"(a) works for me. It\u0027s probably worth adding a bit about what behaviour can be expected if you try to create a tag containing commas.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"f28e6886e2a191fd78a7e088c8aae44349db551b","unresolved":false,"context_lines":[{"line_number":171,"context_line":"the query result. Example that returns servers that have the \"red\" and \"blue\""},{"line_number":172,"context_line":"tags::"},{"line_number":173,"context_line":""},{"line_number":174,"context_line":"    GET /servers/1234567890?tags\u003dred,blue"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":"To request the list of entities that have one or more of a list of given tags,"},{"line_number":177,"context_line":"the ``tags-any`` argument should be set to the list of tags, separated by"}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_57614e10","line":174,"updated":"2015-02-13 15:35:48.000000000","message":"+1, this would be great to have","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f1c9f24c03e22f487b3079862197e68fa4d624de","unresolved":false,"context_lines":[{"line_number":204,"context_line":"    GET /servers/1234567890?tags\u003dred,blue\u0026tags-any\u003dgreen,orange"},{"line_number":205,"context_line":""},{"line_number":206,"context_line":"The above example returns any servers that have the \"red\" and \"blue\" tags, plus"},{"line_number":207,"context_line":"one of \"green\" or \"orange\"."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_38bdb5d8","line":207,"updated":"2015-02-13 10:44:22.000000000","message":"one or more of?","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"ecbfc2d79e0b879c93f0d0ded7e2182a1c42faa8","unresolved":false,"context_lines":[{"line_number":204,"context_line":"    GET /servers/1234567890?tags\u003dred,blue\u0026tags-any\u003dgreen,orange"},{"line_number":205,"context_line":""},{"line_number":206,"context_line":"The above example returns any servers that have the \"red\" and \"blue\" tags, plus"},{"line_number":207,"context_line":"one of \"green\" or \"orange\"."}],"source_content_type":"text/x-rst","patch_set":1,"id":"da86d52c_d6e0d7fc","line":207,"in_reply_to":"da86d52c_38bdb5d8","updated":"2015-02-13 18:42:15.000000000","message":"Correct. I\u0027ll update it in the next revision.","commit_id":"3d5931255acb7ef74eb3dd0c027a497832a8c9d1"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"50560d7caf9e7635020280f8c103e0b02346a3df","unresolved":false,"context_lines":[{"line_number":43,"context_line":"of a resource, a PUT request should be sent to the resource, including not only"},{"line_number":44,"context_line":"the updated tag list, but the complete resource representation in the body. The"},{"line_number":45,"context_line":"update in this case does not need to be limited to tags, other properties can"},{"line_number":46,"context_line":"be updated at the same time. Note that using a PUT request it is possible to"},{"line_number":47,"context_line":"add and/or remove multiple tags in one single operation, simply by sending"},{"line_number":48,"context_line":"the updated tag list with the resource representation."},{"line_number":49,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"da86d52c_84fa1c75","line":46,"updated":"2015-02-18 14:28:09.000000000","message":"Are you missing a word here?  Did you mean:\n\n    Note that *by* using a PUT request, it is possible ...","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"50560d7caf9e7635020280f8c103e0b02346a3df","unresolved":false,"context_lines":[{"line_number":63,"context_line":""},{"line_number":64,"context_line":"Obtaining the Tag List"},{"line_number":65,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"To obtain the tags for a resource, a GET request must be sent to the root"},{"line_number":68,"context_line":"tags URL. On success, the server responds with a 200 status code and the"},{"line_number":69,"context_line":"complete set of tags items in the response body."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da86d52c_a4b72084","line":66,"updated":"2015-02-18 14:28:09.000000000","message":"So a normal GET operation (ie, /servers/detail) will not contain the tags, correct?  I think that this is fine (and preferred) but am wondering if you want to call this out.","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"cfe2245ef46f0e04d1a1f30b3385d479e370d2c7","unresolved":false,"context_lines":[{"line_number":63,"context_line":""},{"line_number":64,"context_line":"Obtaining the Tag List"},{"line_number":65,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"To obtain the tags for a resource, a GET request must be sent to the root"},{"line_number":68,"context_line":"tags URL. On success, the server responds with a 200 status code and the"},{"line_number":69,"context_line":"complete set of tags items in the response body."}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba7be1f8_422ce102","line":66,"in_reply_to":"da86d52c_282cda49","updated":"2015-02-23 16:51:36.000000000","message":"Ahh, yes, sorry I missed that.","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"db94a7d03454fee173909563fbd4322a591b3c22","unresolved":false,"context_lines":[{"line_number":63,"context_line":""},{"line_number":64,"context_line":"Obtaining the Tag List"},{"line_number":65,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"To obtain the tags for a resource, a GET request must be sent to the root"},{"line_number":68,"context_line":"tags URL. On success, the server responds with a 200 status code and the"},{"line_number":69,"context_line":"complete set of tags items in the response body."}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba7be1f8_f6186286","line":66,"in_reply_to":"da86d52c_a4b72084","updated":"2015-02-21 00:07:50.000000000","message":"+1 for clarifying on this point either way","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"0b1b99efcda1772ca02a486b4547a36af1f92272","unresolved":false,"context_lines":[{"line_number":63,"context_line":""},{"line_number":64,"context_line":"Obtaining the Tag List"},{"line_number":65,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"To obtain the tags for a resource, a GET request must be sent to the root"},{"line_number":68,"context_line":"tags URL. On success, the server responds with a 200 status code and the"},{"line_number":69,"context_line":"complete set of tags items in the response body."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da86d52c_282cda49","line":66,"in_reply_to":"da86d52c_a4b72084","updated":"2015-02-21 01:55:16.000000000","message":"Actually no. If you get the top-level resource, it should come with a \"tags\" field. You can edit the tag list by sending a PUT request to the resource with an updated list. This is in the previous section.","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"db94a7d03454fee173909563fbd4322a591b3c22","unresolved":false,"context_lines":[{"line_number":161,"context_line":"GET request to the collection URL, and include query string parameters that"},{"line_number":162,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":163,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":164,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":165,"context_line":"``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba7be1f8_3c365b53","line":164,"updated":"2015-02-21 00:07:50.000000000","message":"alt: The recommended query string arguments for filtering tags are:","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"0b1b99efcda1772ca02a486b4547a36af1f92272","unresolved":false,"context_lines":[{"line_number":161,"context_line":"GET request to the collection URL, and include query string parameters that"},{"line_number":162,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":163,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":164,"context_line":"sorting, etc. The query string argument that are defined are ``tags``,"},{"line_number":165,"context_line":"``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba7be1f8_8a3c5931","line":164,"in_reply_to":"ba7be1f8_3c365b53","updated":"2015-02-21 01:55:16.000000000","message":"Done","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"50560d7caf9e7635020280f8c103e0b02346a3df","unresolved":false,"context_lines":[{"line_number":165,"context_line":"``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da86d52c_e42118b5","line":168,"updated":"2015-02-18 14:28:09.000000000","message":"Please remove references to \"I\" from the guideline.","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"0b1b99efcda1772ca02a486b4547a36af1f92272","unresolved":false,"context_lines":[{"line_number":165,"context_line":"``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."}],"source_content_type":"text/x-rst","patch_set":2,"id":"ba7be1f8_aa491dd2","line":168,"in_reply_to":"da86d52c_e42118b5","updated":"2015-02-21 01:55:16.000000000","message":"Done","commit_id":"df7debab6664e3e823525fbd273ce61fa4866d02"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"b68bca135d2014e6542a65583385538640593261","unresolved":false,"context_lines":[{"line_number":43,"context_line":"of a resource, a PUT request should be sent to the resource, including not only"},{"line_number":44,"context_line":"the updated tag list, but the complete resource representation in the body. The"},{"line_number":45,"context_line":"update in this case does not need to be limited to tags, other properties can"},{"line_number":46,"context_line":"be updated at the same time. Note that using a PUT request it is possible to"},{"line_number":47,"context_line":"add and/or remove multiple tags in one single operation, simply by sending"},{"line_number":48,"context_line":"the updated tag list with the resource representation."},{"line_number":49,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_e22155fd","line":46,"updated":"2015-02-23 16:52:19.000000000","message":"Are you missing a word here? Did you mean:\n\n    Note that *by* using a PUT request, it is possible ...","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"b66fdc4c333a0988ea8196e82e755506e3f79993","unresolved":false,"context_lines":[{"line_number":43,"context_line":"of a resource, a PUT request should be sent to the resource, including not only"},{"line_number":44,"context_line":"the updated tag list, but the complete resource representation in the body. The"},{"line_number":45,"context_line":"update in this case does not need to be limited to tags, other properties can"},{"line_number":46,"context_line":"be updated at the same time. Note that using a PUT request it is possible to"},{"line_number":47,"context_line":"add and/or remove multiple tags in one single operation, simply by sending"},{"line_number":48,"context_line":"the updated tag list with the resource representation."},{"line_number":49,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_5549f289","line":46,"in_reply_to":"ba7be1f8_e22155fd","updated":"2015-02-23 20:33:30.000000000","message":"Done","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":10559,"name":"Steven Kaufer","email":"kaufer@us.ibm.com","username":"kaufer"},"change_message_id":"b68bca135d2014e6542a65583385538640593261","unresolved":false,"context_lines":[{"line_number":165,"context_line":"``tags``, ``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_828419d5","line":168,"updated":"2015-02-23 16:52:19.000000000","message":"Please remove references to \"I\" from the guideline.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"b66fdc4c333a0988ea8196e82e755506e3f79993","unresolved":false,"context_lines":[{"line_number":165,"context_line":"``tags``, ``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_35463e7d","line":168,"in_reply_to":"ba7be1f8_828419d5","updated":"2015-02-23 20:33:30.000000000","message":"Done","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"14cdd1abcf47a0d3b360371fa710054ba80c0363","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_60b9d6e8","line":171,"updated":"2015-02-23 20:52:15.000000000","message":"I don\u0027t know about the lack of support for repeating query string arguments in clients or servers. Can you point me to something that does not support this standard?","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"4f01254971a9996a413c4165f3661d755199f77d","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_b4cbf71c","line":171,"in_reply_to":"ba7be1f8_4c96c84d","updated":"2015-02-24 10:58:42.000000000","message":"Do we have an opportunity here to clarify and improve libraries? The core Python libs (parse_qs, FieldStorage and the like) support multiple uses of the same parameter and always have. They return a dict of lists, even when there is only one parameter.\n\nDoing a bit of searching the web shows that the multiple query strings is not standardized but tag\u003dfoo\u0026tag\u003dbar is somewhat of a de facto standard.\n\nI\u0027d prefer to go with the standard set by the standard lib and use that to drive improvement in what could be argued to be broken libraries. Aren\u0027t these sorts of things why we have tests and why we enjoy the opportunities provided by open source? It can break and then we can fix it.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"5e94edf521eaa54c05dbd9cdb31d80ca24d39259","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_027e57e4","line":171,"in_reply_to":"ba7be1f8_4c96c84d","updated":"2015-02-24 17:11:26.000000000","message":"So part of this was also the idea that most naive clients would also have issues supporting repeated query parameters. There\u0027s also the subjective part of this that the query string is more elegant, and the practical one that if we ever use URI Templates (RFC 6570), then repeated query parameters aren\u0027t supported there, but this style of query parameter is supported. Future-proofing APIs seems like a good idea to me at least.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"8058ecfff681ad9080c836a0aff0bf6c6d26b887","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_4c96c84d","line":171,"in_reply_to":"ba7be1f8_60b9d6e8","updated":"2015-02-23 23:50:39.000000000","message":"We had a discussion about this when we were reviewing the sorting guideline document. I think the issue that was mentioned was that any framework that exposes the query string as a key/value data structure (such as a Python dict) would not be able to represent the repeated args unless it does some special handling such as setting the value to an array.\n\nI don\u0027t have a specific client that has this problem (maybe Steven Kaufer remembers if specific examples were mentioned?), but I agreed that it seemed likely that a naive library would not do this correctly. For that reason we agreed to not allow repeated args.\n\nHere I\u0027m just being consistent with our decision.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"4e196f256d97d95e0a0f34c95ca48cb92d529192","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_ce28cc88","line":171,"in_reply_to":"ba7be1f8_b4cbf71c","updated":"2015-02-24 17:13:09.000000000","message":"Not relying on undefined and possibly non-uniform behaviors in different libraries and frameworks makes it harder to provide a simple and uniform experience to API consumers in all languages. Improving other libraries is not a stated goal of this WG.\n\nAs one other consideration that was not mentioned, the comma-delimited list generally makes more efficient use of limited URL lengths when used in conjunction with OpenStack\u0027s long resource URLs, existing filters and sorting preferences.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1069cb8bc82dea18edcfeee82af6de81327a07b7","unresolved":false,"context_lines":[{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. Here I"},{"line_number":169,"context_line":"decided to be consistent with the sorting guideline document, for which it"},{"line_number":170,"context_line":"was decided that repeating query string arguments is not a good idea due to"},{"line_number":171,"context_line":"not having good support among web clients and servers."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":174,"context_line":"should be set to the desired tag name. Example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba7be1f8_58b74d3a","line":171,"in_reply_to":"ba7be1f8_b4cbf71c","updated":"2015-02-24 11:55:39.000000000","message":"Note, too, that if you create a form with four inputs named tag browsers will produce four query parameters upon submit\n\n    file:///tmp/form.html?tag\u003done\u0026tag\u003dtwo\u0026tag\u003dthree\u0026tag\u003dfour\n\nIt\u0027s the way things work \"on the web\". Our APIs are on the web, they should work that way.","commit_id":"bc9652d5d8edc9faafe760e6ad8fba5b52737591"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"6a47402a1f4a37c9b40e81dc0280f226a179009e","unresolved":false,"context_lines":[{"line_number":19,"context_line":""},{"line_number":20,"context_line":"Tags are strings attached to an entity with the purpose of classification into"},{"line_number":21,"context_line":"groups. To simplify requests that specify lists of tags, the comma character"},{"line_number":22,"context_line":"is not allowed to be in a tag name."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"An entity can have zero, one or more tags associated with it, for that"},{"line_number":25,"context_line":"reason the recommended representation within the parent entity is a list."}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_a7911d9b","line":22,"updated":"2015-02-24 00:10:07.000000000","message":"probably should restrict to printable characters too - eg no CR, LF, spaces etc. Probably need to block 4 character unicode chars too.","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"44784b9aca78107c048ba6b93cc004505b7b5e30","unresolved":false,"context_lines":[{"line_number":19,"context_line":""},{"line_number":20,"context_line":"Tags are strings attached to an entity with the purpose of classification into"},{"line_number":21,"context_line":"groups. To simplify requests that specify lists of tags, the comma character"},{"line_number":22,"context_line":"is not allowed to be in a tag name."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"An entity can have zero, one or more tags associated with it, for that"},{"line_number":25,"context_line":"reason the recommended representation within the parent entity is a list."}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_87ca596c","line":22,"in_reply_to":"ba7be1f8_a7911d9b","updated":"2015-02-24 00:50:17.000000000","message":"What\u0027s the problem with 4-char unicode?","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"6a47402a1f4a37c9b40e81dc0280f226a179009e","unresolved":false,"context_lines":[{"line_number":70,"context_line":""},{"line_number":71,"context_line":"Example request::"},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"    GET /servers/1234567890/tags"},{"line_number":74,"context_line":""},{"line_number":75,"context_line":"Response::"},{"line_number":76,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_67148544","line":73,"updated":"2015-02-24 00:10:07.000000000","message":"Doesn\u0027t this line conflict with line 29 where it says you can get a list of tags from a get on the resource - ie it is an alternative way stated here, not the only (must) way","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"44784b9aca78107c048ba6b93cc004505b7b5e30","unresolved":false,"context_lines":[{"line_number":70,"context_line":""},{"line_number":71,"context_line":"Example request::"},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"    GET /servers/1234567890/tags"},{"line_number":74,"context_line":""},{"line_number":75,"context_line":"Response::"},{"line_number":76,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_82916754","line":73,"in_reply_to":"ba7be1f8_67148544","updated":"2015-02-24 00:50:17.000000000","message":"This is an alternative, it does not conflict with the previous option. The request in line 29 returns the entire resource, including tags. This one returns just the tags.\n\nNote the beginning of the section Tags Resource URLs, which says \"sometimes it may be inconvenient o work with the tags portion of a resource uisng the complete resource representation\".","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":7253,"name":"Jason Dunsmore","email":"jasondunsmore@gmail.com","username":"jbd"},"change_message_id":"00ac63d6855dfcd9d41fe8c189f52176276451fc","unresolved":false,"context_lines":[{"line_number":162,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":163,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":164,"context_line":"sorting, etc. The recommended query string arguments for filtering tags are"},{"line_number":165,"context_line":"``tags``, ``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. The preference"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_1e0e8be5","line":165,"updated":"2015-02-24 18:51:44.000000000","message":"s/not-any-tags/not-tags-any/","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"68a017a1061780c0377e98c66972056262062237","unresolved":false,"context_lines":[{"line_number":162,"context_line":"define the query. These arguments can be combined with other arguments, such"},{"line_number":163,"context_line":"as those that perform additional filtering outside of tags, pagination,"},{"line_number":164,"context_line":"sorting, etc. The recommended query string arguments for filtering tags are"},{"line_number":165,"context_line":"``tags``, ``tags-any``, ``not-tags`` and ``not-any-tags``."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Note that once again this is different than the nova specification, which"},{"line_number":168,"context_line":"uses repeated ``tag`` query arguments to specify a list of tags. The preference"}],"source_content_type":"text/x-rst","patch_set":4,"id":"ba7be1f8_84530c6a","line":165,"in_reply_to":"ba7be1f8_1e0e8be5","updated":"2015-02-24 19:41:01.000000000","message":"Done","commit_id":"75a75b5e9c44bdcf049d197e7d1f1b0925aa9b6d"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"709b1c712b111e8351d40710d7a1503e987092ad","unresolved":false,"context_lines":[{"line_number":129,"context_line":"appending the tag name to the root tag URL."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"To insert a single tag without having to send the entire tag list, the client"},{"line_number":132,"context_line":"should send a PUT request to the inidividual tag URL. On success, the server"},{"line_number":133,"context_line":"responds with a 201 status code and includes the new tag\u0027s URL in the"},{"line_number":134,"context_line":"``Location`` header in the response."},{"line_number":135,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"9a80dd14_307309b6","line":132,"updated":"2015-03-10 16:19:16.000000000","message":"should this explicitly mention an empty body?","commit_id":"1deaae9f79c03afb4eee5cc3226ee3f1fef85d0b"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"7e640e8de5c5d7fe93169215937a05692e56927b","unresolved":false,"context_lines":[{"line_number":129,"context_line":"appending the tag name to the root tag URL."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"To insert a single tag without having to send the entire tag list, the client"},{"line_number":132,"context_line":"should send a PUT request to the inidividual tag URL. On success, the server"},{"line_number":133,"context_line":"responds with a 201 status code and includes the new tag\u0027s URL in the"},{"line_number":134,"context_line":"``Location`` header in the response."},{"line_number":135,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"9a80dd14_94b8f72b","line":132,"in_reply_to":"9a80dd14_307309b6","updated":"2015-03-11 14:31:53.000000000","message":"Does it need to? It seems fairly clear that it shouldn\u0027t need anything else to create a tag since tags are simply strings.","commit_id":"1deaae9f79c03afb4eee5cc3226ee3f1fef85d0b"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"4dbe27c6742183165a78c213fda96238c20b15c3","unresolved":false,"context_lines":[{"line_number":129,"context_line":"appending the tag name to the root tag URL."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"To insert a single tag without having to send the entire tag list, the client"},{"line_number":132,"context_line":"should send a PUT request to the inidividual tag URL. On success, the server"},{"line_number":133,"context_line":"responds with a 201 status code and includes the new tag\u0027s URL in the"},{"line_number":134,"context_line":"``Location`` header in the response."},{"line_number":135,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"9a80dd14_af9cc15e","line":132,"in_reply_to":"9a80dd14_307309b6","updated":"2015-03-11 16:17:00.000000000","message":"I can add it when/if I need to do another revision.","commit_id":"1deaae9f79c03afb4eee5cc3226ee3f1fef85d0b"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"f9e06afb09ea1deb8ae8eb9f2a2961731c4b26be","unresolved":false,"context_lines":[{"line_number":97,"context_line":"following articles:"},{"line_number":98,"context_line":""},{"line_number":99,"context_line":"- http://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/"},{"line_number":100,"context_line":"- http://haacked.com/archive/2009/06/25/json-hijacking.aspx/"},{"line_number":101,"context_line":""},{"line_number":102,"context_line":"Modifying the Tag List"},{"line_number":103,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"}],"source_content_type":"text/x-rst","patch_set":7,"id":"fa963961_9b20559d","line":100,"updated":"2015-03-27 16:50:09.000000000","message":"oooh, nasty indeed. I wasn\u0027t aware of this.","commit_id":"649db146c1a1481e5ed488766e816cb1fe8d444d"},{"author":{"_account_id":2889,"name":"Aeva Black","email":"aeva.online@gmail.com","username":"tenbrae"},"change_message_id":"0118c81d7d0cde077f667563be78cda348e58ee8","unresolved":false,"context_lines":[{"line_number":187,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":188,"context_line":"should be set to the desired tag name. Example::"},{"line_number":189,"context_line":""},{"line_number":190,"context_line":"    GET /servers/1234567890?tags\u003dred"},{"line_number":191,"context_line":""},{"line_number":192,"context_line":"To request the list of entities that have two or more tags, the ``tags``"},{"line_number":193,"context_line":"argument should be set to the list of tags, separated by commas. In this"}],"source_content_type":"text/x-rst","patch_set":7,"id":"dac4157f_a6b75885","line":190,"updated":"2015-04-21 21:21:51.000000000","message":"This, and the following GET examples, should not include the server resource id \"1234567890\". As the intent is to search for entities that have a particular tag, the URI should be the resource type, not a specific resource ID. Thus, the examples should be:\n\n  GET /servers?tags\u003dred\n\nand so on.","commit_id":"649db146c1a1481e5ed488766e816cb1fe8d444d"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"635c4e2feacfbf7ebeb4642e32c2a2a00de1f5cb","unresolved":false,"context_lines":[{"line_number":187,"context_line":"To request the list of entities that have a single tag, ``tags`` argument"},{"line_number":188,"context_line":"should be set to the desired tag name. Example::"},{"line_number":189,"context_line":""},{"line_number":190,"context_line":"    GET /servers/1234567890?tags\u003dred"},{"line_number":191,"context_line":""},{"line_number":192,"context_line":"To request the list of entities that have two or more tags, the ``tags``"},{"line_number":193,"context_line":"argument should be set to the list of tags, separated by commas. In this"}],"source_content_type":"text/x-rst","patch_set":7,"id":"dac4157f_57da6879","line":190,"in_reply_to":"dac4157f_a6b75885","updated":"2015-04-21 22:23:40.000000000","message":"Oh, good catch. You are correct, this should be the collection URL.","commit_id":"649db146c1a1481e5ed488766e816cb1fe8d444d"}]}