)]}'
{"guidelines/etags.rst":[{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"d8649f14c7ec2c8ac60d67d71163ccb8f389baa1","unresolved":false,"context_lines":[],"source_content_type":"","patch_set":1,"id":"9a061dce_5ef365d6","updated":"2016-04-05 17:33:51.000000000","message":"Is a file of its own the right place for this or should it go in the generic http file?","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"d8649f14c7ec2c8ac60d67d71163ccb8f389baa1","unresolved":false,"context_lines":[{"line_number":34,"context_line":"one already in hand. This is very useful when validating cached GET"},{"line_number":35,"context_line":"requests (the ETag answers the question \"is what I have in my cache"},{"line_number":36,"context_line":"the same as what the server would give me?\") but is also useful for"},{"line_number":37,"context_line":"avoiding the lost update problem."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":"If the scenario described above is modified to use ETags it would"},{"line_number":40,"context_line":"work like this:"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_beb8c1e6","line":37,"updated":"2016-04-05 17:33:51.000000000","message":"I feel obliged to mention the caching aspects of etags but leave out any more details. Does it need to be mentioned or does adding it cause noise?","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11904,"name":"Sean McGinnis","email":"sean.mcginnis@gmail.com","username":"SeanM"},"change_message_id":"6027270dc76f29c37ad2017ce8444fa34b1b91b1","unresolved":false,"context_lines":[{"line_number":43,"context_line":"  response header named ``ETag`` that is the same for both clients"},{"line_number":44,"context_line":"  (let\u0027s make the ETag \u0027red57\u0027)."},{"line_number":45,"context_line":"  (Details on ETag generation can be found below)."},{"line_number":46,"context_line":"* The both make changes to their local representation."},{"line_number":47,"context_line":"* Client B does a ``PUT /some/resource`` and includes a header"},{"line_number":48,"context_line":"  named If-Match_ with a value of ``red57``. The request is"},{"line_number":49,"context_line":"  successful because the ETag sent in the request is the same as the"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_1e7e0d19","line":46,"range":{"start_line":46,"start_character":2,"end_line":46,"end_character":5},"updated":"2016-04-05 17:37:15.000000000","message":"/The/They/","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5c0d77e1fc08d3833e794324af5a6fc8251d8d0","unresolved":false,"context_lines":[{"line_number":43,"context_line":"  response header named ``ETag`` that is the same for both clients"},{"line_number":44,"context_line":"  (let\u0027s make the ETag \u0027red57\u0027)."},{"line_number":45,"context_line":"  (Details on ETag generation can be found below)."},{"line_number":46,"context_line":"* The both make changes to their local representation."},{"line_number":47,"context_line":"* Client B does a ``PUT /some/resource`` and includes a header"},{"line_number":48,"context_line":"  named If-Match_ with a value of ``red57``. The request is"},{"line_number":49,"context_line":"  successful because the ETag sent in the request is the same as the"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_5efec537","line":46,"in_reply_to":"9a061dce_1e7e0d19","updated":"2016-04-05 17:42:41.000000000","message":"Done","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"d8649f14c7ec2c8ac60d67d71163ccb8f389baa1","unresolved":false,"context_lines":[{"line_number":62,"context_line":"-------"},{"line_number":63,"context_line":""},{"line_number":64,"context_line":"If a service accepts PUT requests and needs to avoid lost updates it"},{"line_number":65,"context_line":"can do so by:"},{"line_number":66,"context_line":""},{"line_number":67,"context_line":"* Sending responses to GET requests with a ETag header."},{"line_number":68,"context_line":"* Requiring clients to send an If-Match header with a valid ETag when"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_9ea21dad","line":65,"updated":"2016-04-05 17:33:51.000000000","message":"Should this more strongly state: If you do PUT you need this!","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11904,"name":"Sean McGinnis","email":"sean.mcginnis@gmail.com","username":"SeanM"},"change_message_id":"6027270dc76f29c37ad2017ce8444fa34b1b91b1","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  XML and JSON representations of the same version of a resource"},{"line_number":86,"context_line":"  should have different ETags."},{"line_number":87,"context_line":"* Different from version to version."},{"line_number":88,"context_line":"* Not based on something that will when the system restarts."},{"line_number":89,"context_line":"  For example not be based on inodes or database keys that are ints"},{"line_number":90,"context_line":"  or other non-universal identifiers."},{"line_number":91,"context_line":"* Not be based on hashes of strings that do not have reliable"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_fec6b947","line":88,"updated":"2016-04-05 17:37:15.000000000","message":"that will... change?","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":177,"name":"Alex Meade","email":"mr.alex.meade@gmail.com","username":"alex-meade"},"change_message_id":"ac4b6a8d457e4324d9dbf201139d4056aa7bc752","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  XML and JSON representations of the same version of a resource"},{"line_number":86,"context_line":"  should have different ETags."},{"line_number":87,"context_line":"* Different from version to version."},{"line_number":88,"context_line":"* Not based on something that will when the system restarts."},{"line_number":89,"context_line":"  For example not be based on inodes or database keys that are ints"},{"line_number":90,"context_line":"  or other non-universal identifiers."},{"line_number":91,"context_line":"* Not be based on hashes of strings that do not have reliable"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_de9ad562","line":88,"range":{"start_line":88,"start_character":34,"end_line":88,"end_character":35},"updated":"2016-04-05 17:35:48.000000000","message":"will change when?","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5c0d77e1fc08d3833e794324af5a6fc8251d8d0","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  XML and JSON representations of the same version of a resource"},{"line_number":86,"context_line":"  should have different ETags."},{"line_number":87,"context_line":"* Different from version to version."},{"line_number":88,"context_line":"* Not based on something that will when the system restarts."},{"line_number":89,"context_line":"  For example not be based on inodes or database keys that are ints"},{"line_number":90,"context_line":"  or other non-universal identifiers."},{"line_number":91,"context_line":"* Not be based on hashes of strings that do not have reliable"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_1e044d48","line":88,"in_reply_to":"9a061dce_de9ad562","updated":"2016-04-05 17:42:41.000000000","message":"Done","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a5c0d77e1fc08d3833e794324af5a6fc8251d8d0","unresolved":false,"context_lines":[{"line_number":85,"context_line":"  XML and JSON representations of the same version of a resource"},{"line_number":86,"context_line":"  should have different ETags."},{"line_number":87,"context_line":"* Different from version to version."},{"line_number":88,"context_line":"* Not based on something that will when the system restarts."},{"line_number":89,"context_line":"  For example not be based on inodes or database keys that are ints"},{"line_number":90,"context_line":"  or other non-universal identifiers."},{"line_number":91,"context_line":"* Not be based on hashes of strings that do not have reliable"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a061dce_beec4190","line":88,"in_reply_to":"9a061dce_fec6b947","updated":"2016-04-05 17:42:41.000000000","message":"Done","commit_id":"bfc2eb9874c521d386aabad45cf1d9d2eb3c998a"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"4ebe0f7a0a328402c3e455ebdf2feb70da5f8948","unresolved":false,"context_lines":[{"line_number":93,"context_line":"  of the JSON string that represents a resource. If the ordering in"},{"line_number":94,"context_line":"  that JSON is not guaranteed, the ETag is not useful."},{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Ideally they should be fast to calculate or or if not fast then easy"},{"line_number":97,"context_line":"to store (when the representation is written). A hash of a last"},{"line_number":98,"context_line":"udpated timestamp and the content-type can work, but only if updates"},{"line_number":99,"context_line":"are less frequent than clock updates."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a061dce_e183be02","line":96,"range":{"start_line":96,"start_character":41,"end_line":96,"end_character":46},"updated":"2016-04-05 17:58:41.000000000","message":"double","commit_id":"b489dfaf2deb09595df874d5611bd7f02f307902"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"a79f4b53c8cd4a4379b92a038127519a1961fc53","unresolved":false,"context_lines":[{"line_number":96,"context_line":"Ideally they should be fast to calculate or or if not fast then easy"},{"line_number":97,"context_line":"to store (when the representation is written). A hash of a last"},{"line_number":98,"context_line":"udpated timestamp and the content-type can work, but only if updates"},{"line_number":99,"context_line":"are less frequent than clock updates."},{"line_number":100,"context_line":""},{"line_number":101,"context_line":".. _lost update problem: https://www.w3.org/1999/04/Editing/"},{"line_number":102,"context_line":".. _ETags: https://tools.ietf.org/html/rfc7232#section-2.3"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9a061dce_01cb5273","line":99,"updated":"2016-04-05 17:56:38.000000000","message":"Might make sense to explain why this isn\u0027t required for the usual POSTS-to-create that we do.\n\nAs well as how it can be used for DELETE too to state \"only delete this if what you\u0027ve have is what I have\".","commit_id":"b489dfaf2deb09595df874d5611bd7f02f307902"},{"author":{"_account_id":1207,"name":"Duncan Thomas","email":"duncan.thomas@gmail.com","username":"duncan-thomas"},"change_message_id":"1db939a35a3086d1623ae48b576c83c1270f4b3b","unresolved":false,"context_lines":[{"line_number":164,"context_line":"  in an ``If-Match`` header sent to the image resource."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":".. note:: In both of the above scenarios the semantics of ETags are being"},{"line_number":167,"context_line":"          badly and baldly violated. An ETag is not a magic key to unlock"},{"line_number":168,"context_line":"          a resource and make it writable. It is a value used to"},{"line_number":169,"context_line":"          determine if two representations of the same resource are"},{"line_number":170,"context_line":"          in fact the same. In the situations above they are"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a061dce_26dac34c","line":167,"range":{"start_line":167,"start_character":10,"end_line":167,"end_character":26},"updated":"2016-04-06 12:25:46.000000000","message":"badly and boldly?","commit_id":"30dc5a2a08841d5675e999532e82820447c22043"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"097090ec0763663997ec95c120faf5d72175ed01","unresolved":false,"context_lines":[{"line_number":164,"context_line":"  in an ``If-Match`` header sent to the image resource."},{"line_number":165,"context_line":""},{"line_number":166,"context_line":".. note:: In both of the above scenarios the semantics of ETags are being"},{"line_number":167,"context_line":"          badly and baldly violated. An ETag is not a magic key to unlock"},{"line_number":168,"context_line":"          a resource and make it writable. It is a value used to"},{"line_number":169,"context_line":"          determine if two representations of the same resource are"},{"line_number":170,"context_line":"          in fact the same. In the situations above they are"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a061dce_86fc6f73","line":167,"in_reply_to":"9a061dce_26dac34c","updated":"2016-04-06 12:30:25.000000000","message":"Was an intentional choice: http://www.macmillandictionary.com/dictionary/british/baldly\n\nBut yeah, is probably not clear, will replace it after enough comments come in for another version.","commit_id":"30dc5a2a08841d5675e999532e82820447c22043"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"39477c5f7f08151f6bd7009f3b0e77ac9aa6cb2f","unresolved":false,"context_lines":[{"line_number":42,"context_line":"* Client A and client B both ``GET /some/resource``, including a"},{"line_number":43,"context_line":"  response header named ``ETag`` that is the same for both clients"},{"line_number":44,"context_line":"  (let\u0027s make the ETag \u0027red57\u0027)."},{"line_number":45,"context_line":"  (Details on ETag generation can be found below)."},{"line_number":46,"context_line":"* They both make changes to their local representation."},{"line_number":47,"context_line":"* Client B does a ``PUT /some/resource`` and includes a header"},{"line_number":48,"context_line":"  named If-Match_ with a value of ``red57``. The request is"}],"source_content_type":"text/x-rst","patch_set":4,"id":"9a061dce_346f32fd","line":45,"updated":"2016-04-07 17:13:17.000000000","message":"An external person without credentials notes that this parenthetical statement is bad in all kinds of ways.","commit_id":"b27e5115aeef51ccba801dcae28314b7e0f25eb5"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"1b8157abf47ec51078eb2cf4b3b47649062c6ff1","unresolved":false,"context_lines":[{"line_number":116,"context_line":"* Not be based on hashes of strings that do not have reliable"},{"line_number":117,"context_line":"  ordering. For example it can be tempting to make md5 or sha hashes"},{"line_number":118,"context_line":"  of the JSON string that represents a resource. If the ordering in"},{"line_number":119,"context_line":"  that JSON is not guaranteed, the ETag is not useful."},{"line_number":120,"context_line":""},{"line_number":121,"context_line":"Ideally they should be fast to calculate or if not fast then easy"},{"line_number":122,"context_line":"to store (when the representation is written). A hash of a last"}],"source_content_type":"text/x-rst","patch_set":4,"id":"9a061dce_6f855acd","line":119,"updated":"2016-04-07 16:16:37.000000000","message":"All of these points dance around the notion of a canonical representation of the resource.\n\nWould it make sense to put a stake in the ground and say the ETag should be based on the canonical representation of the resource? \n\nWith the definition of canonical being dependent on the system/resource.","commit_id":"b27e5115aeef51ccba801dcae28314b7e0f25eb5"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"39477c5f7f08151f6bd7009f3b0e77ac9aa6cb2f","unresolved":false,"context_lines":[{"line_number":116,"context_line":"* Not be based on hashes of strings that do not have reliable"},{"line_number":117,"context_line":"  ordering. For example it can be tempting to make md5 or sha hashes"},{"line_number":118,"context_line":"  of the JSON string that represents a resource. If the ordering in"},{"line_number":119,"context_line":"  that JSON is not guaranteed, the ETag is not useful."},{"line_number":120,"context_line":""},{"line_number":121,"context_line":"Ideally they should be fast to calculate or if not fast then easy"},{"line_number":122,"context_line":"to store (when the representation is written). A hash of a last"}],"source_content_type":"text/x-rst","patch_set":4,"id":"9a061dce_7fa18393","line":119,"in_reply_to":"9a061dce_6f855acd","updated":"2016-04-07 17:13:17.000000000","message":"Is there a canonical representation type? And is it common between the openstack services? If not, then we can\u0027t really provide much guidance that isn\u0027t hand wavey or distracting.\n\nAt the same time, etag generation can have pretty interesting performance impact depending on context (e.g. hashing an ordered dict of nest ordered dicts can get very wacky and most of the time is way overkill), so it seemed better to inform people of the job of the etag and the tradeoffs in different strategies and let them walk away from this with multiple (but limited) choices on how to do things that will work for them.\n\nAnd finally, in my mental model of HTTP apis, the server doesn\u0027t have a canonical representation. It only has the resource in the abstract and it gains a representation once it has been requested. Since OpenStack doesn\u0027t generally do content negotiation that doesn\u0027t mean much in practice, but if we were ever to have it or want to encourage it then keeping the server agnostic about representations seems sane. These sort of mental meanderings seem out of place when people have never even heard of etags in the first place and aren\u0027t that savvy to the concept of representations in the first place.\n\nSo in the end it seemed better to just leave \"canonical\" out.","commit_id":"b27e5115aeef51ccba801dcae28314b7e0f25eb5"},{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"02544408182904a534cfcb59ad2c3c933f0e5aca","unresolved":false,"context_lines":[{"line_number":175,"context_line":"  this would require a GET of the metadata resource to determine the"},{"line_number":176,"context_line":"  ETag."},{"line_number":177,"context_line":""},{"line_number":178,"context_line":"  If this is a problem, an optimization to work around this is to"},{"line_number":179,"context_line":"  allow the ETag of the image resource to be an acceptable ETag of"},{"line_number":180,"context_line":"  the metadata resource when provided in an ``If-Match`` header."},{"line_number":181,"context_line":"  If this is done, then it is important that the reverse not be"}],"source_content_type":"text/x-rst","patch_set":6,"id":"1a122d0e_e9dfef66","line":178,"updated":"2016-04-19 16:40:03.000000000","message":"Cool idea. I\u0027ve not seen that before.","commit_id":"959e6cdceb5dfc70edf9fcb56adf4be91869d63a"}]}