)]}'
{"guidelines/http.rst":[{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"eb90b01def3a0486c6573a7b5f3cb7cec0899adf","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":132,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":133,"context_line":"feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a016987_d4e0ccfc","line":133,"updated":"2015-05-15 13:02:31.000000000","message":"i think there should be one more word here, \"...the user that the feature was not...\"","commit_id":"1287d2fe9d0add13f1f28b20a6f93b85cc3300b2"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"76aa6fbd8bd4c71b95b2f1821be04ffc77545154","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":132,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":133,"context_line":"feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a016987_d7a8cedd","line":133,"in_reply_to":"7a016987_d4e0ccfc","updated":"2015-05-15 13:23:11.000000000","message":"good catch, updating.","commit_id":"1287d2fe9d0add13f1f28b20a6f93b85cc3300b2"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"8579b5da5c7ffaf3ff9c547a82ec19dc17aace38","unresolved":false,"context_lines":[{"line_number":125,"context_line":""},{"line_number":126,"context_line":"We live in a very different world today, dominated by Apache and"},{"line_number":127,"context_line":"Nginx. As such 501 is something you\u0027d be unlikely to see in the"},{"line_number":128,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":129,"context_line":"our own."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"}],"source_content_type":"text/x-rst","patch_set":2,"id":"7a016987_77bfdafb","line":128,"updated":"2015-05-15 13:28:52.000000000","message":"s/it\u0027s/its/","commit_id":"9d3f8e6306026334c6e23a95e778b21e404b7d5e"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"8579b5da5c7ffaf3ff9c547a82ec19dc17aace38","unresolved":false,"context_lines":[{"line_number":129,"context_line":"our own."},{"line_number":130,"context_line":""},{"line_number":131,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":132,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":133,"context_line":"the feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7a016987_b7e8b2e3","line":132,"updated":"2015-05-15 13:28:52.000000000","message":"If you do another round of changes, can you add a sample error message here? I\u0027m imagining something like:\n\n\"400 BadRequest: Feature WhizzBang is not implemented in this \u003cproject\u003e installation. For more information, see \u003clink to feature toggle\u003e\"","commit_id":"9d3f8e6306026334c6e23a95e778b21e404b7d5e"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"7b8ee533ec8a02becda1f7ba4d56ad1edf9704ce","unresolved":false,"context_lines":[{"line_number":114,"context_line":"in OpenStack. This section attempts to enumerate them with reasons why"},{"line_number":115,"context_line":"they were wrong, and propose future alternatives."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Use of 501 - Method Not Found"},{"line_number":118,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"Some time in the Folsom era projects started using 501 for \"Feature"}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_85004003","line":117,"updated":"2015-05-22 19:13:05.000000000","message":"The HTTP specification calls this error \"Not Implemented\". Regardless of how we feel about the use of this response, I think the correct name should be given.","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"85bf57ed3e36bdafa4edede00f27c01f1a923f05","unresolved":false,"context_lines":[{"line_number":114,"context_line":"in OpenStack. This section attempts to enumerate them with reasons why"},{"line_number":115,"context_line":"they were wrong, and propose future alternatives."},{"line_number":116,"context_line":""},{"line_number":117,"context_line":"Use of 501 - Method Not Found"},{"line_number":118,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":119,"context_line":""},{"line_number":120,"context_line":"Some time in the Folsom era projects started using 501 for \"Feature"}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_aee294ff","line":117,"in_reply_to":"7a016987_85004003","updated":"2015-05-27 14:29:38.000000000","message":"+1","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"fdfece5a30dc8b0caad0be24d3cfb17803166703","unresolved":false,"context_lines":[{"line_number":125,"context_line":"something very specific in HTTP, it means an HTTP Method. One of GET /"},{"line_number":126,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":127,"context_line":""},{"line_number":128,"context_line":"The purpose of the 501 error was to indicate to the client that PATCH"},{"line_number":129,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":130,"context_line":"resource on the server. And appropriate client action is to blacklist"},{"line_number":131,"context_line":"PATCH and ensure no code attempts to use this. This comes from early"}],"source_content_type":"text/x-rst","patch_set":5,"id":"5afe65bd_b7286287","line":128,"updated":"2015-06-04 15:26:44.000000000","message":"Is there a reference for this interpretation? While they do give that as an example in http://tools.ietf.org/html/rfc7231#section-6.6.2 I don\u0027t think that\u0027s the only reason it should be used. An in that case I wonder why 405 is not the preferred way to tell the client about the error.","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"e3f45ac5c7afa5b361cfa8ad1ee5ebef8bb5eda1","unresolved":false,"context_lines":[{"line_number":135,"context_line":""},{"line_number":136,"context_line":"We live in a very different world today, dominated by Apache and"},{"line_number":137,"context_line":"Nginx. As such 501 is something you\u0027d be unlikely to see in the"},{"line_number":138,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":139,"context_line":"our own."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_bf587dfb","line":138,"updated":"2015-05-15 18:45:59.000000000","message":"s/it\u0027s/its/","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"8cb7b5bd03dfa61fa8f304b54f5e20142d4e7b71","unresolved":false,"context_lines":[{"line_number":138,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":139,"context_line":"our own."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":142,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":143,"context_line":"the feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_71d23402","line":141,"updated":"2015-05-15 23:31:40.000000000","message":"So you are proposing to raise a 4xx client side error even if it\u0027s a server side implementation limitation? IMO, it\u0027s really not user-friendly","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"b147e69804d4bdb13e600f5f04276dbe80f724b1","unresolved":false,"context_lines":[{"line_number":138,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":139,"context_line":"our own."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":142,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":143,"context_line":"the feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_d1f1e86b","line":141,"in_reply_to":"7a016987_71d23402","updated":"2015-05-15 23:45:39.000000000","message":"But, it has the advantage of not being completely wrong and potentially having dramatically dangerous consequences with caching servers.\n\nIt\u0027s not a server error. The server didn\u0027t do a wrong thing. The client asked for a thing the server doesn\u0027t do. That\u0027s a bad request.\n\nThis is where a narrow reading of HTTP gets folks in trouble. See discussion on - https://review.openstack.org/#/c/181283","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"58a4b26fc8db2049be5f3e523ba6684d37c46c52","unresolved":false,"context_lines":[{"line_number":138,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":139,"context_line":"our own."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":142,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":143,"context_line":"the feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_03f2936f","line":141,"in_reply_to":"7a016987_c3d47bbe","updated":"2015-05-16 00:24:37.000000000","message":"imo, 400 \u0027Bad Request\u0027 would be fine in [2] if it was documented in API definition that libvirt driver does not support the feature.","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"0d56dc917d2261477f5baa9fe6d41f5915713dd0","unresolved":false,"context_lines":[{"line_number":138,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":139,"context_line":"our own."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":142,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":143,"context_line":"the feature was not implemented in that cloud."}],"source_content_type":"text/x-rst","patch_set":5,"id":"7a016987_c3d47bbe","line":141,"in_reply_to":"7a016987_d1f1e86b","updated":"2015-05-16 00:20:44.000000000","message":"400 Bad Request RFC definition[1] is:\n\n The request could not be understood by the server due to malformed syntax\n\nBut the error is raised not due to malformed syntax (as the request is valid according to API definition) but due to server limitations (as server implementation is not able to comply with API definition).\n\n[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html\n[2] http://lists.openstack.org/pipermail/openstack-dev/2012-December/003759.html","commit_id":"209831a965be7cb36a77ffd53b85a92f1622d94d"},{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"211b3ec5186e5fdfa2afbf31ce13273eaaf76ed0","unresolved":false,"context_lines":[{"line_number":147,"context_line":"Common Mistakes"},{"line_number":148,"context_line":"---------------"},{"line_number":149,"context_line":"There are many common mistakes that have been made in implementations"},{"line_number":150,"context_line":"in OpenStack. This section attempts to enumerate them with reasons why"},{"line_number":151,"context_line":"they were wrong, and propose future alternatives."},{"line_number":152,"context_line":""},{"line_number":153,"context_line":"Use of 501 - Not Implemented"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_7f48af87","line":150,"updated":"2015-06-08 17:17:41.000000000","message":"s/in/of/","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7599316bc813ec3c0a6bfcdfaa1a5bc72d953827","unresolved":false,"context_lines":[{"line_number":163,"context_line":""},{"line_number":164,"context_line":"The purpose of the 501 error was to indicate to the client that POST"},{"line_number":165,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":166,"context_line":"resource on the server. And appropriate client action is to blacklist"},{"line_number":167,"context_line":"POST and ensure no code attempts to use this. This comes from early"},{"line_number":168,"context_line":"days of HTTP where there were hundreds of commercial HTTP server"},{"line_number":169,"context_line":"implementations, and the assumption that all HTTP methods would be"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_84f7a2f4","line":166,"updated":"2015-06-08 16:25:53.000000000","message":"s/And/An/","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7599316bc813ec3c0a6bfcdfaa1a5bc72d953827","unresolved":false,"context_lines":[{"line_number":164,"context_line":"The purpose of the 501 error was to indicate to the client that POST"},{"line_number":165,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":166,"context_line":"resource on the server. And appropriate client action is to blacklist"},{"line_number":167,"context_line":"POST and ensure no code attempts to use this. This comes from early"},{"line_number":168,"context_line":"days of HTTP where there were hundreds of commercial HTTP server"},{"line_number":169,"context_line":"implementations, and the assumption that all HTTP methods would be"},{"line_number":170,"context_line":"handled by a server was not something the vendors could agree on. This"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_64c6e69b","line":167,"updated":"2015-06-08 16:25:53.000000000","message":"s/from early/from the early/","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7599316bc813ec3c0a6bfcdfaa1a5bc72d953827","unresolved":false,"context_lines":[{"line_number":171,"context_line":"usage was clarified in `rfc 7231 section 6.6.2"},{"line_number":172,"context_line":"\u003chttps://tools.ietf.org/html/rfc7231#section-6.6.2\u003e`_."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":"If we assume the follow rfc statement to be true: \"This is the"},{"line_number":175,"context_line":"appropriate response when the server does not recognize the request"},{"line_number":176,"context_line":"method and is not capable of supporting it for any resource.\" that is"},{"line_number":177,"context_line":"irreconcilable with a narrower reading, because we\u0027ve said all clients"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_c43b5a9b","line":174,"updated":"2015-06-08 16:25:53.000000000","message":"s/follow/following/","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"71fef72c0c43a52aaf0c1007687b789019abba2d","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_8a21f24f","line":189,"updated":"2015-06-08 15:03:12.000000000","message":"Still, why returning a 4xx client error when the request is valid according to API definition but the server is not able to handle it (ie: server implementation does not comply with API definition)?","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"667e58aec1af75d0ba2b8f0fe177a258babfaa41","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_56d3a004","line":189,"in_reply_to":"3afb71cf_13953add","updated":"2015-06-08 16:00:01.000000000","message":"\"I think the underlying concept that needs to be kept in mind here is that application code should not be generating 5xx responses\" Why? Returning 5xx is not \"bad\", it just means that the server is not able to handle a valid request because it crashed (\u003d\u003e 500), because of resource exhaustion (\u003d\u003e 503), ...\n\n\"The correct response would be something along the lines of 400 \"We don\u0027t support that aggregation, but we do support these.\" Nope, everything is about API contract and who respects it or not. In this case, the client request respects API contract and the server does not so it\u0027s a server error.\n\nRemainder: \n\n\n400 Bad Request RFC definition[1] is:\n\n The request could not be understood by the server due to malformed syntax\n\nAccording to API contract, in our cases, the request is not malformed as it respects API contract.\n\n422 Unprocessable Entity RFC definition [2] is:\n\nThe 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415(Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.\n\nimo, 422 matchs less than 400 and 422 is not part of http1.1?\n\n\n* [1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html \n* [2] http://www.webdav.org/specs/rfc4918.html#STATUS_422","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"211b3ec5186e5fdfa2afbf31ce13273eaaf76ed0","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_cac003e3","line":189,"in_reply_to":"3afb71cf_19c0bb7a","updated":"2015-06-08 17:17:41.000000000","message":"I\u0027m very interested in this 4xx vs. 5xx discussion too. Some of our backends in Keystone don\u0027t implement the entire API. A read-only catalog is the primary example. We currently return 501, but after reading the clarification in the newer spec I agrees that it\u0027s incorrect.\n\nIn this case a think a 405 is a better return code since: \"the method received in the request-line is known by the origin server but not supported by the target resource\". This is assuming that we\u0027d send a proper Allow header too.\n\nIs this assessment incorrect?","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"51f1bbb0dd5ae34a98dfa389fe4ea14a92ecf66c","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_ff725f48","line":189,"in_reply_to":"3afb71cf_56d3a004","updated":"2015-06-08 16:49:33.000000000","message":"Cedric, if you\u0027re going to reference RFCs, reference the correct RFCs: https://tools.ietf.org/html/rfc7231#section-6.5 has the section of 4xx errors. The description for 400 is\n\n    The 400 (Bad Request) status code indicates that the server cannot or\n    will not process the request due to something that is perceived to be\n    a client error (e.g., malformed request syntax, invalid request\n    message framing, or deceptive request routing).\n\nSpecifically note \"the server cannot or will not process the request due to something that is perceived to be a client error\". The client should be aware that a cloud does not implement resize for an instance so the client erred in requesting that Nova resize the instance. The server neither can nor will process that request because that extension was disabled.\n\nHopefully this clears up your confusion.\n\nAlso, regardless of whether 422 is included in 7230-7235, it\u0027s used by a number of well-designed APIs to indicate that validation has failed.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"e6abc772b553821fcff99a6259674f82805dd7e7","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_b0be5cd2","line":189,"in_reply_to":"3afb71cf_707224af","updated":"2015-06-08 15:17:34.000000000","message":"The client asked for a \"thing\" which is valid according to API definition, so it\u0027s a valid request?","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"7a99b8978e7fb6f7f06a74e452814af9bb0f0911","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_19c0bb7a","line":189,"in_reply_to":"3afb71cf_7671fcdf","updated":"2015-06-08 16:03:14.000000000","message":"@Sean: \"It just didn\u0027t do that thing.\" so it just don\u0027t respect API contract.\n\nI am not saying we should or not use 501, i am just saying using a 4xx error for such case is a mistake as the main point is who respects or not the API contract.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"bbafcca0068b12a53cf2a8881c68ad641dba5e19","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_707224af","line":189,"in_reply_to":"3afb71cf_8a21f24f","updated":"2015-06-08 15:10:27.000000000","message":"Because the client asked the cloud to do a thing that\u0027s not a thing. For the same reason that 404 exists. The client asked for not possible thing.\n\nThe whole 5xx space is not intended for applications to intentionally use. It\u0027s about low level server failing to fundamentally handle HTTP itself, not anything about the application payload.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"d4f8df62a6a8421fb593a67add6a7593bafdde29","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_13953add","line":189,"in_reply_to":"3afb71cf_b0be5cd2","updated":"2015-06-08 15:41:25.000000000","message":"Cedric you\u0027re conflating 400 Bad Request with one possible definition of that error code, namely \"The request was ill formatted\" which can also be responded to with 422 Validation Failed. In other words, 400 Bad Request is somewhat ambiguous and could just as easily mean what Sean is putting forth here.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"6dbec90e43c9e86de9b4df8a3e70025663bdf09d","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_7671fcdf","line":189,"in_reply_to":"3afb71cf_b0be5cd2","updated":"2015-06-08 15:56:35.000000000","message":"I also think it\u0027s important to read the section header of 5xx\n\nrfc 7231 section 6.6\n\n\"The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method.\"\n\n*method* means something very specific for http, one of GET, POST, PUT, etc.\n\nThe server was not in error for not implementing \u0027resize\u0027 on a nova compute server resource. It just didn\u0027t do that thing. It was a client error to ask the server to do a thing it can\u0027t do. \n\nBut again, there is a reason why this section comes after the http background section. There continues to be this assumption that HTTP specification was designed for dynamic applications. It was not. It was designed for resources on a network, primarily static. Assuming there is always an HTTP code for all circumstances is a fallacy.\n\nIt\u0027s also worth nothing that the O\u0027Reilly book on REST makes the same basic statement around 501 and why it exists - https://books.google.com/books?id\u003dXUaErakHsoAC\u0026pg\u003dPA387\u0026lpg\u003dPA387\u0026dq\u003drestful+web+services+501\u0026source\u003dbl\u0026ots\u003d5kejGntNtw\u0026sig\u003duRE2az6bLVM4dfjZwlMCKgmS2fs\u0026hl\u003den\u0026sa\u003dX\u0026ei\u003dwbp1VeX3EOLLsASjqq64Aw\u0026ved\u003d0CB8Q6AEwAA#v\u003donepage\u0026q\u003drestful%20web%20services%20501\u0026f\u003dfalse (pg 387 if you have it in hard cover)","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"65acd6b171459a9de78e3a6008b592c4bc37901c","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_33d836ef","line":189,"in_reply_to":"3afb71cf_b0be5cd2","updated":"2015-06-08 15:40:57.000000000","message":"It\u0027s not valid for _this_ API. If the client becomes aware of _this_ APIs capabilities they may be able to reconstruct their request and have success. Therefore something in 4xx is legit.\n\nI think the underlying concept that needs to be kept in mind here is that application code should not be generating 5xx responses, only the web server itself (the thing doing the http protocol on the wire) and a last ditch piece of middleware that catches any untrapped application code exceptions[1] and packages them in a \"safe\" fashion.\n\nOnce we get in our heads that OpenStack API code is not the HTTP server, just the web application, these boundaries about what response codes go where becomes much more clear. Application code can and should generate \u003e\u003d200 and \u003c500. Server code can and should generate 1xx and 5xx.\n\nIf you are writing application code such that you feel like 501 is a good idea (e.g. you think that 501 is the correct response when a piece of functionality is not available in the _application_ by virtue of that application\u0027s configuration in this specific instance) then, simply put, you are doing it wrong. Either you\u0027ve incorrectly defined the resources in your API or you are looking for a shortcut.\n\nI\u0027ll give an example of where it is being done incorrectly. In gnocchi[2] a middleware[3] is used to transform a generic NotImplementedException into a 501. In the API the situation where this exception can happen is when someone requests an aggregation that some backend doesn\u0027t implement. That means they\u0027ve made a request of a URL that _exists_ (doesn\u0027t return a 404) using a method GET that is correct (so 405 is not correct) with a parameter (for the aggregation) that is not valid for a specific implementation. The correct response would be something along the lines of 400 \"We don\u0027t support that aggregation, but we do support these.\"\n\nThe only situation where 501 would be strictly correct here is if the web server that is hosting the gnocchi app doesn\u0027t support GET (clearly it does).\n\nSomewhat less strict would be if the URL represented a verb (such as /server/{id}/action) and that entire URL was unavailable (not just invalid by way of parameter). Of course if you are making URLs that represent verbs YOU ARE DOING IT COMPLETELY WRONG anyway, so don\u0027t go there.\n\n(Note that a) I\u0027m core on gnocchi but the rest have decided this is okay for so meh to me b) you can decide to do things incorrectly in your app too, but that\u0027s no reason to write guidelines that are incorrect. We should have correct guidelines and then make individual choices about whether we wish to violate them.)\n\nSo, to sum: Don\u0027t use 501. If you think you should be using 501, don\u0027t, and look at what you really want to convey to the client.\n\n[1] Of which there should be very very very few, and when they do happen they should be logged and debugged so that the application code can correctly turn them into 4xx responses.\n\n[2] https://github.com/openstack/gnocchi\n\n[3] https://github.com/openstack/gnocchi/blob/master/gnocchi/rest/app.py#L82","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":8124,"name":"cbrandily","email":"zzelle@gmail.com","username":"cbrandily"},"change_message_id":"3d360c98a703102f54148768b8184f845f9fbef9","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_17f63fd7","line":189,"in_reply_to":"3afb71cf_cac003e3","updated":"2015-06-08 17:47:52.000000000","message":"@Ian: i still strongly disagree. \n\nThe aim of an API contract is to define how interact clients with servers. A request should be \"perceived to be a client error\" when the request does not respect the API contract and perceived to be a server error when the server is not able to respect the API contract (because of a crash , an implementation limitation, resource exhaustion, etc.).\n\nOtherwise it means that we don\u0027t care about the API and i don\u0027t understand why we lose time to microversion the API.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"92658927267f7a844a422e612ad9cebe883422eb","unresolved":false,"context_lines":[{"line_number":186,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":187,"context_line":"our own."},{"line_number":188,"context_line":""},{"line_number":189,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":190,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":191,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":192,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_6d580633","line":189,"in_reply_to":"3afb71cf_cac003e3","updated":"2015-06-08 18:18:10.000000000","message":"David, maybe. 405 is the per resource version of 501 (which is the whole server). So if a resource fails to support POST, that\u0027s the valid response for it. However, that is a default cachable entity, which means you are saying that resource can never support POST.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"9f89ee6390480df725fa876675eec438265f85f0","unresolved":false,"context_lines":[{"line_number":194,"context_line":"\"Feature Not Implemented\" is when we POST an operation to a URI of the"},{"line_number":195,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":196,"context_line":"operations on it were not supported. Returning a 404 (which is by"},{"line_number":197,"context_line":"default cachable) would make the client believe /resource/{id}/action"},{"line_number":198,"context_line":"did not exist at all on the server."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_4ad893ef","line":197,"updated":"2015-06-08 17:15:47.000000000","message":"Minor point, but I don\u0027t think we should be encouraging the /resource/{id}/action paradigm, since it\u0027s not RESTful...","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"2c741eefd645cd1c03959248250c2293f4c76d06","unresolved":false,"context_lines":[{"line_number":194,"context_line":"\"Feature Not Implemented\" is when we POST an operation to a URI of the"},{"line_number":195,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":196,"context_line":"operations on it were not supported. Returning a 404 (which is by"},{"line_number":197,"context_line":"default cachable) would make the client believe /resource/{id}/action"},{"line_number":198,"context_line":"did not exist at all on the server."}],"source_content_type":"text/x-rst","patch_set":7,"id":"3afb71cf_0d6512e0","line":197,"in_reply_to":"3afb71cf_4ad893ef","updated":"2015-06-08 18:19:30.000000000","message":"sure, I hate that as well. But it\u0027s a lot of places, and given how controversial this whole 501 thing is, I feel like we shouldn\u0027t go there until next cycle. Alternative recommendations are likely going to take a long time to bake out.","commit_id":"a4bf5a85eaa62e55258814b011d07d9cad0a3ace"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"a442ca09e310b9bb26177445f26d8126b223d0c0","unresolved":false,"context_lines":[{"line_number":139,"context_line":"on the payload in the response body."},{"line_number":140,"context_line":""},{"line_number":141,"context_line":"Common Mistakes"},{"line_number":142,"context_line":"---------------"},{"line_number":143,"context_line":""},{"line_number":144,"context_line":"There are many common mistakes that have been made in the"},{"line_number":145,"context_line":"implementations of RESTful APIs in OpenStack. This section attempts to"}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_f1acaf8d","line":142,"updated":"2015-06-18 07:28:24.000000000","message":"I\u0027ve done so many of them that I could make this section a book on its own.","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":1669,"name":"Julien Danjou","display_name":"jd","email":"julien@danjou.info","username":"jdanjou"},"change_message_id":"587ecb93f44b0fdc6da55699e11bb00ae482a37f","unresolved":false,"context_lines":[{"line_number":153,"context_line":"Not Implemented\" - `Discussion on openstack-dev"},{"line_number":154,"context_line":"\u003chttp://lists.openstack.org/pipermail/openstack-dev/2012-December/003759.html\u003e`_"},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"This is a completely incorrect reading of HTTP. \"Method\" means"},{"line_number":157,"context_line":"something very specific in HTTP, it means an HTTP Method. One of GET /"},{"line_number":158,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":159,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_5a655942","line":156,"updated":"2015-06-25 09:19:18.000000000","message":"Funny enough, I\u0027d say that this is a correct reading of HTTP and from what I glanced from the thread, a lot of people agrees with that 501 is not tied to the method request.\n\nIs there any evidence of that being wrong?","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"d3909abaf0a25ffb66a930f728d744b60899b655","unresolved":false,"context_lines":[{"line_number":153,"context_line":"Not Implemented\" - `Discussion on openstack-dev"},{"line_number":154,"context_line":"\u003chttp://lists.openstack.org/pipermail/openstack-dev/2012-December/003759.html\u003e`_"},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"This is a completely incorrect reading of HTTP. \"Method\" means"},{"line_number":157,"context_line":"something very specific in HTTP, it means an HTTP Method. One of GET /"},{"line_number":158,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":159,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a4dcd0f_5891f745","line":156,"in_reply_to":"9a41bdd9_8a237dbc","updated":"2015-08-12 21:00:33.000000000","message":"When you say \"Method\" means ... it is unclear in which context the word \"method\" appears. You need to clarify that this is mentioned in the HTTP spec as an appropriate use for this status code.","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"ddce758d4228019d019d36a893cf657f6bf33eac","unresolved":false,"context_lines":[{"line_number":153,"context_line":"Not Implemented\" - `Discussion on openstack-dev"},{"line_number":154,"context_line":"\u003chttp://lists.openstack.org/pipermail/openstack-dev/2012-December/003759.html\u003e`_"},{"line_number":155,"context_line":""},{"line_number":156,"context_line":"This is a completely incorrect reading of HTTP. \"Method\" means"},{"line_number":157,"context_line":"something very specific in HTTP, it means an HTTP Method. One of GET /"},{"line_number":158,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":159,"context_line":""}],"source_content_type":"text/x-rst","patch_set":9,"id":"9a41bdd9_8a237dbc","line":156,"in_reply_to":"fa32b979_5a655942","updated":"2015-07-16 11:51:39.000000000","message":"Yes, a lot of evidence of that fact, see all the rest of the conversation below.","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"d3909abaf0a25ffb66a930f728d744b60899b655","unresolved":false,"context_lines":[{"line_number":158,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"The purpose of the 501 error was to indicate to the client that POST"},{"line_number":161,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":162,"context_line":"resource on the server. An appropriate client action is to blacklist"},{"line_number":163,"context_line":"POST and ensure no code attempts to use this. This comes from the"},{"line_number":164,"context_line":"early days of HTTP where there were hundreds of commercial HTTP server"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a4dcd0f_389aeb62","line":161,"updated":"2015-08-12 21:00:33.000000000","message":"s/now/known/","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"2ee9770e4457147b4f7c061bf6f4d732334debef","unresolved":false,"context_lines":[{"line_number":158,"context_line":"HEAD / POST / PUT / PATCH / OPTIONS / TRACE."},{"line_number":159,"context_line":""},{"line_number":160,"context_line":"The purpose of the 501 error was to indicate to the client that POST"},{"line_number":161,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":162,"context_line":"resource on the server. An appropriate client action is to blacklist"},{"line_number":163,"context_line":"POST and ensure no code attempts to use this. This comes from the"},{"line_number":164,"context_line":"early days of HTTP where there were hundreds of commercial HTTP server"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a4dcd0f_be9b1566","line":161,"in_reply_to":"1a4dcd0f_389aeb62","updated":"2015-08-13 16:33:36.000000000","message":"Actually \"now\" is correct above. Sean is saying that the purpose of the 501 is not and was never an appropriate method to call on any resource of the server...","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"d3909abaf0a25ffb66a930f728d744b60899b655","unresolved":false,"context_lines":[{"line_number":160,"context_line":"The purpose of the 501 error was to indicate to the client that POST"},{"line_number":161,"context_line":"is not now, and never will be an appropriate method to call on any"},{"line_number":162,"context_line":"resource on the server. An appropriate client action is to blacklist"},{"line_number":163,"context_line":"POST and ensure no code attempts to use this. This comes from the"},{"line_number":164,"context_line":"early days of HTTP where there were hundreds of commercial HTTP server"},{"line_number":165,"context_line":"implementations, and the assumption that all HTTP methods would be"},{"line_number":166,"context_line":"handled by a server was not something the vendors could agree on. This"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a4dcd0f_78095394","line":163,"updated":"2015-08-12 21:00:33.000000000","message":"I have never seen an implementation of an HTTP client that \"blacklists\" a method after a 501 is returned. Do you have any references for this?","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"238c3cda47c78031a0083d348a93524d6cef7bf3","unresolved":false,"context_lines":[{"line_number":178,"context_line":""},{"line_number":179,"context_line":"We live in a very different world today, dominated by Apache and"},{"line_number":180,"context_line":"Nginx. As such 501 is something you\u0027d be unlikely to see in the"},{"line_number":181,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":182,"context_line":"our own."},{"line_number":183,"context_line":""},{"line_number":184,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"}],"source_content_type":"text/x-rst","patch_set":9,"id":"3a50d1a3_3840b933","line":181,"updated":"2015-07-22 23:23:21.000000000","message":"While what you write here is correct, I don\u0027t see replacing the semantics of 501 as a mortal sin. After all it would not be the first thing invented for a purpose but famous for another (coca-cola anyone?)\n\nbtw, \"it\u0027s\" should be \"its\" :))))","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":13995,"name":"Nate Johnston","email":"nate.johnston@redhat.com","username":"natejohnston"},"change_message_id":"5204360e29f1bb44c0a41312c3bb35550690d7c3","unresolved":false,"context_lines":[{"line_number":178,"context_line":""},{"line_number":179,"context_line":"We live in a very different world today, dominated by Apache and"},{"line_number":180,"context_line":"Nginx. As such 501 is something you\u0027d be unlikely to see in the"},{"line_number":181,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":182,"context_line":"our own."},{"line_number":183,"context_line":""},{"line_number":184,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"}],"source_content_type":"text/x-rst","patch_set":9,"id":"da20952f_637da9e6","line":181,"in_reply_to":"3a50d1a3_3840b933","updated":"2015-08-27 19:42:41.000000000","message":"I think replacing 501 errors with something in the 400 family is more correct because 50x errors all indicate that the server is not functioning as it should, whereas errors in the 4xx series indicate that the client has done something that the server in the normal course of action cannot fulfill.  If an Openstack API wishes to indicate that a piece of functionality is not implemented yet, the server can answer that while working as designed, which to me indicates a 4xx error is indicated.\n\nWhat additional meaning do we wish to convey when a customer calls  /api/some_feature_that_is_not_implemented that is different from a customer calling /api/completely_random_url (the 404 error case)?","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"d3909abaf0a25ffb66a930f728d744b60899b655","unresolved":false,"context_lines":[{"line_number":181,"context_line":"wild. However that doesn\u0027t mean we can replace it\u0027s definition with"},{"line_number":182,"context_line":"our own."},{"line_number":183,"context_line":""},{"line_number":184,"context_line":"Going forward projects should use a 400 \u0027BadRequest\u0027 response for this"},{"line_number":185,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":186,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":187,"context_line":"be appropriate in some situations when the URI will never"}],"source_content_type":"text/x-rst","patch_set":9,"id":"1a4dcd0f_db6ae1b2","line":184,"updated":"2015-08-12 21:00:33.000000000","message":"I think suggesting the 400 status code for feature not implemented without explaining your reasoning is misleading, as this condition can be seen as a server error, more akin to the 5xx errors than the 4xx.\n\nReally what I read between the lines here is that there is no appropriate server or user error for this condition. You are proposing the 400 is the best compromise (I hope you agree the 400 is also not appropriate for this situation).","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"a442ca09e310b9bb26177445f26d8126b223d0c0","unresolved":false,"context_lines":[{"line_number":185,"context_line":"condition, plus a more specific error message back to the user that"},{"line_number":186,"context_line":"the feature was not implemented in that cloud. 404 \u0027NotFound\u0027 may also"},{"line_number":187,"context_line":"be appropriate in some situations when the URI will never"},{"line_number":188,"context_line":"exist. However one of the most common places where we would return"},{"line_number":189,"context_line":"\"Feature Not Implemented\" is when we POST an operation to a URI of the"},{"line_number":190,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":191,"context_line":"operations on it were not supported. Returning a 404 (which is by"}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_71341f49","line":188,"updated":"2015-06-18 07:28:24.000000000","message":"Technically you can never know if the URL will never exist, but this is just pedant me talking.","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"a442ca09e310b9bb26177445f26d8126b223d0c0","unresolved":false,"context_lines":[{"line_number":190,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":191,"context_line":"operations on it were not supported. Returning a 404 (which is by"},{"line_number":192,"context_line":"default cachable) would make the client believe /resource/{id}/action"},{"line_number":193,"context_line":"did not exist at all on the server."}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_71d09fc9","line":193,"updated":"2015-06-18 07:28:24.000000000","message":"a 404 however would make sense is \"resource\" did not exist.\nThere are cases like... you know Neutron. When you get a 404 because a resource does not exist, whereas the truth is that the resource does not exist on that specific instance of the server, because the extensions that implements it is not defined.\n\nThis was a place were some idiot (me) proposed initially we should instead use the 501. I justified myself saying I was talking about Jeans from a famous brand. I think 400 is the only one that makes some sense.\n\nHowever, as a side note, I think you too are aware that we\u0027re using 400 for quite a lot of stuff. and the only way of distinguishing the various errors is the message. Messages are good for humans, not so for machines. Are we still completely -2 on the idea of sending application error codes within error response bodies?","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"129f6e591413a919083121437ae1fd81bcdc2e6c","unresolved":false,"context_lines":[{"line_number":190,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":191,"context_line":"operations on it were not supported. Returning a 404 (which is by"},{"line_number":192,"context_line":"default cachable) would make the client believe /resource/{id}/action"},{"line_number":193,"context_line":"did not exist at all on the server."}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_898eddce","line":193,"in_reply_to":"fa32b979_71d09fc9","updated":"2015-06-22 11:55:44.000000000","message":"Actually, I think that in general people are pro structured error messages back in the payload. Which I think would make a ton of sense. We just won\u0027t use HTTP error codes for that. \n\nSee https://review.openstack.org/#/c/167793/ - my only concern there is to make it a bit more human readable as well as machine readable (i.e. meaningful strings for error ids instead of uuids)","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"1e7fc3c6370dc43209d00b161bd1005d310460fb","unresolved":false,"context_lines":[{"line_number":190,"context_line":"form /resource/{id}/action. Clearly that URI is found, however some"},{"line_number":191,"context_line":"operations on it were not supported. Returning a 404 (which is by"},{"line_number":192,"context_line":"default cachable) would make the client believe /resource/{id}/action"},{"line_number":193,"context_line":"did not exist at all on the server."}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa32b979_20715b0c","line":193,"in_reply_to":"fa32b979_898eddce","updated":"2015-06-24 19:49:27.000000000","message":"this makes sense.","commit_id":"04a85d4111fcb63659d31c8043638560bb6c342c"}]}