)]}'
{"guidelines/http/methods.rst":[{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"228c568cee8cdaf05cf8dd7dfa0742cc671bfb44","unresolved":false,"context_lines":[{"line_number":84,"context_line":"  an error if the resource doesn\u0027t exist. In the rare use cases where it is"},{"line_number":85,"context_line":"  necessary to verify that a resource was deleted, you should first call a GET"},{"line_number":86,"context_line":"  or HEAD on that resource, and return an error if it doesn\u0027t exist."},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"HTTP request bodies are theoretically allowed for all methods except TRACE,"},{"line_number":89,"context_line":"however they are not commonly used except in PUT, POST and PATCH. Because of"},{"line_number":90,"context_line":"this, they may not be supported properly by some client frameworks, and you"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_f675f586","line":87,"updated":"2018-11-08 16:39:29.000000000","message":"you mentioned not receiving an error from this call, do we need to say something about 5xx errors that may arise?","commit_id":"aac1c672cf9919e1cda40c0bd7493c5721681a49"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"79413ac30948e2dcfdcd9d063a0baf0c91a365ea","unresolved":false,"context_lines":[{"line_number":84,"context_line":"  an error if the resource doesn\u0027t exist. In the rare use cases where it is"},{"line_number":85,"context_line":"  necessary to verify that a resource was deleted, you should first call a GET"},{"line_number":86,"context_line":"  or HEAD on that resource, and return an error if it doesn\u0027t exist."},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"HTTP request bodies are theoretically allowed for all methods except TRACE,"},{"line_number":89,"context_line":"however they are not commonly used except in PUT, POST and PATCH. Because of"},{"line_number":90,"context_line":"this, they may not be supported properly by some client frameworks, and you"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_9dcdbc5c","line":87,"in_reply_to":"3f79a3b5_ac8410b3","updated":"2018-11-08 20:52:20.000000000","message":"i definitely read it as 404 errors, was just curious. thanks, i\u0027m good with this.","commit_id":"aac1c672cf9919e1cda40c0bd7493c5721681a49"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"773765bfa5f496009bd8275b72c54a6383d9ed4b","unresolved":false,"context_lines":[{"line_number":84,"context_line":"  an error if the resource doesn\u0027t exist. In the rare use cases where it is"},{"line_number":85,"context_line":"  necessary to verify that a resource was deleted, you should first call a GET"},{"line_number":86,"context_line":"  or HEAD on that resource, and return an error if it doesn\u0027t exist."},{"line_number":87,"context_line":""},{"line_number":88,"context_line":"HTTP request bodies are theoretically allowed for all methods except TRACE,"},{"line_number":89,"context_line":"however they are not commonly used except in PUT, POST and PATCH. Because of"},{"line_number":90,"context_line":"this, they may not be supported properly by some client frameworks, and you"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_ac8410b3","line":87,"in_reply_to":"3f79a3b5_f675f586","updated":"2018-11-08 18:21:58.000000000","message":"No, if they are receiving 5xx, there are bigger problems. What I mean is that some implementations will return 404 Not Found if the resource doesn\u0027t exist. I\u0027ll update the language.","commit_id":"aac1c672cf9919e1cda40c0bd7493c5721681a49"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"ca542a49cb806c6dff8bc24008ff954517309b87","unresolved":false,"context_lines":[{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; it should *never* return a `404"},{"line_number":81,"context_line":"  Not Found` error. What that means is that you should be able to call DELETE"},{"line_number":82,"context_line":"  many times against the same resource and not receive an error because the"},{"line_number":83,"context_line":"  resource doesn\u0027t exist. The way to understand this is that issuing a DELETE"},{"line_number":84,"context_line":"  against a resource means \"I just want to ensure that this resource isn\u0027t"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_6ee793b0","line":81,"updated":"2018-11-13 09:20:52.000000000","message":"This is too absolute. You should clarify that DELETE on a bad URI should return a 404. That is:\n\n    DELETE /resource_providers/{uuid}\n\nshould never 404, it should be idempotent as described. But:\n\n    DELETE /resource_provider/{uuid}\n\n_should_ 404 because there is no possible entity at that URI at no point in time in the past or future.","commit_id":"68ba1c5539a97e111a1d9f5df450e603c5ef8f09"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1e2cd56343ac7ad84ce528dc2165f09b44a309d6","unresolved":false,"context_lines":[{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; it should *never* return a `404"},{"line_number":81,"context_line":"  Not Found` error. What that means is that you should be able to call DELETE"},{"line_number":82,"context_line":"  many times against the same resource and not receive an error because the"},{"line_number":83,"context_line":"  resource doesn\u0027t exist. The way to understand this is that issuing a DELETE"},{"line_number":84,"context_line":"  against a resource means \"I just want to ensure that this resource isn\u0027t"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_66db254c","line":81,"in_reply_to":"3f79a3b5_6ee793b0","updated":"2018-11-14 10:15:15.000000000","message":"++ good catch","commit_id":"68ba1c5539a97e111a1d9f5df450e603c5ef8f09"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"22c4ac7f7b60131ae870759a57f92f81ac7a4081","unresolved":false,"context_lines":[{"line_number":77,"context_line":"  states **GET is the primary mechanism of information retrieval and the"},{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; it should *never* return a `404"},{"line_number":81,"context_line":"  Not Found` error simply because the specified resource does not exist; you"},{"line_number":82,"context_line":"  can, however, still return a 400 if the URI itself is invalid. What this"},{"line_number":83,"context_line":"  means is that you should be able to call DELETE many times against the same"},{"line_number":84,"context_line":"  resource and not receive an error because the resource doesn\u0027t exist. The way"},{"line_number":85,"context_line":"  to understand this is that issuing a DELETE against a resource means \"I just"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3f79a3b5_8df1b59a","line":82,"range":{"start_line":80,"start_character":46,"end_line":82,"end_character":63},"updated":"2018-11-14 22:11:13.000000000","message":"I\u0027m sorry, this, to me, is completely wrong, and this is one of the hills I will die on.\n\nIf a URI is well-formed, it is platonically valid, and thus should be a 404 if there is no resource with that identity at the target host. That is the absolute root principle of HTTP and to say otherwise would completely kill any claims we have to credibility.\n\n    DELETE /invalid_resource_type/{uuid}\n\nmust be a 404 exactly because\n\n   GET /invalid_resource_type/{uuid}\n\nmust be a 404.\n\nWhere there is room to quibble is when query parameters get involved, but for so-called \"paths\" only, there isn\u0027t.\n\nThe idempotency argument can be used to support my position: DELETE /invalid_resource_type/{uuid} should always be 404, because there is no point in time in the current definition of resource reality at which it could ever be a 200 when GET. Or to turn it inside out: If DELETE wasn\u0027t idempotent, there\u0027s no situation where a DELETE that had a 204 could then become a 404 because it would always be 404: It can\u0027t ever be there. It\u0027s not an inavlid URI, it\u0027s just not here (it might be somewhere else).\n\n\nThe fundamental principle I\u0027m working from here is that the thing that matters the most in all of HTTP is the URI. It is _the_ thing that matters.","commit_id":"6694d8f8af9eaaf84300ec900052bc942d85f8d8"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"b712454c21d388f557061c6fc280b30093cfe4e0","unresolved":false,"context_lines":[{"line_number":77,"context_line":"  states **GET is the primary mechanism of information retrieval and the"},{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; it should *never* return a `404"},{"line_number":81,"context_line":"  Not Found` error simply because the specified resource does not exist; you"},{"line_number":82,"context_line":"  can, however, still return a 400 if the URI itself is invalid. What this"},{"line_number":83,"context_line":"  means is that you should be able to call DELETE many times against the same"},{"line_number":84,"context_line":"  resource and not receive an error because the resource doesn\u0027t exist. The way"},{"line_number":85,"context_line":"  to understand this is that issuing a DELETE against a resource means \"I just"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3f79a3b5_fe2c8301","line":82,"range":{"start_line":80,"start_character":46,"end_line":82,"end_character":63},"in_reply_to":"3f79a3b5_8df1b59a","updated":"2018-11-15 16:22:07.000000000","message":"So let me rephrase what you\u0027re saying to make sure I\u0027m following. Given the following URI:\n\n /resource_type/resource_id\n\nwe will first validate that `resource_type` is valid (i.e., something the system can understand). If not, return a 404 no matter what method is called on it.\n\nIf `resource_type` is understandable by the system, any call to DELETE will never return 404.\n\nIs that accurate?","commit_id":"6694d8f8af9eaaf84300ec900052bc942d85f8d8"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6e585f532258c7cd5af61c7d43eb1d0815009219","unresolved":false,"context_lines":[{"line_number":77,"context_line":"  states **GET is the primary mechanism of information retrieval and the"},{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; it should *never* return a `404"},{"line_number":81,"context_line":"  Not Found` error simply because the specified resource does not exist; you"},{"line_number":82,"context_line":"  can, however, still return a 400 if the URI itself is invalid. What this"},{"line_number":83,"context_line":"  means is that you should be able to call DELETE many times against the same"},{"line_number":84,"context_line":"  resource and not receive an error because the resource doesn\u0027t exist. The way"},{"line_number":85,"context_line":"  to understand this is that issuing a DELETE against a resource means \"I just"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3f79a3b5_b90aa51c","line":82,"range":{"start_line":80,"start_character":46,"end_line":82,"end_character":63},"in_reply_to":"3f79a3b5_fe2c8301","updated":"2018-11-15 16:34:48.000000000","message":"\u003e we will first validate that `resource_type` is valid (i.e.,\n \u003e something the system can understand). If not, return a 404 no\n \u003e matter what method is called on it.\n\nSort of, that\u0027s how the web works, as a general rule.\n\nIn most implementations it is built into whatever the routing or dispatching tool is: if a URI matches to the map you proceed deeper into the system. If the URI doesn\u0027t match, you get a 404.\n\nWith the caveat that the URI is the entire thing, not some chunk of it. There is no \u0027resource_type\u0027. There is \u0027/resource_type/resource_id\u0027.","commit_id":"6694d8f8af9eaaf84300ec900052bc942d85f8d8"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"fe99cf0b262078c96e632875112ebb456214672b","unresolved":false,"context_lines":[{"line_number":78,"context_line":"  focus of almost all performance optimizations.**."},{"line_number":79,"context_line":""},{"line_number":80,"context_line":"* The **DELETE** method should be idempotent; calling it multiple times against"},{"line_number":81,"context_line":"  the same resource should return the same result. It should not matter if the"},{"line_number":82,"context_line":"  resource exists or not, as DELETE should be interpreted as \"I want to ensure"},{"line_number":83,"context_line":"  that this resource no longer exists\". This eliminates the need for every"},{"line_number":84,"context_line":"  client of your API having to add handlers for 404s from their DELETE calls,"},{"line_number":85,"context_line":"  because in the overwhelming majority of cases they do not care as long as the"},{"line_number":86,"context_line":"  resource is gone. In those rare cases where it is important to know whether a"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3f79a3b5_5356d0d2","line":83,"range":{"start_line":81,"start_character":51,"end_line":83,"end_character":39},"updated":"2018-12-13 16:35:07.000000000","message":"I disagree that this interpretation is practical, even if it\u0027s more correct from theoretical standpoint.","commit_id":"92390889e64ba63b04145dd6362614de4ffc0c2d"}]}