)]}'
{"guidelines/http.rst":[{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"c6254bc98455bffb811b2dc112632c8c75e10fad","unresolved":false,"context_lines":[{"line_number":41,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"These codes represent that the server has generated an error or is"},{"line_number":44,"context_line":"incapable of performing the requested method. They **must not** be returned"},{"line_number":45,"context_line":"by application code and should only be generated by the HTTP framework in"},{"line_number":46,"context_line":"response to internal errors (for example, unhandled exceptions)."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"5afe65bd_eb965c93","line":44,"updated":"2015-06-02 14:26:23.000000000","message":"Keystone does this in a variety of cases that I consider valid:\n  1. Instead of letting exceptions propagate up we\u0027ll catch, log and then raise an exception that represents a 500. http://git.openstack.org/cgit/openstack/keystone/tree/keystone/token/providers/pkiz.py#n45\n  2. We explicitly raise a 501 when something isn\u0027t implemented. Certain backends are missing functionality (templated catalog) and we\u0027ll send a 501 to let the client know.","commit_id":"f3d3052138c75289c0c3c355030f1bc19f4a5ba2"},{"author":{"_account_id":7725,"name":"David Stanek","email":"dstanek@dstanek.com","username":"dstanek"},"change_message_id":"bc0829b05a399536255df40d38e0026cbd1ea993","unresolved":false,"context_lines":[{"line_number":41,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"These codes represent that the server has generated an error or is"},{"line_number":44,"context_line":"incapable of performing the requested method. They **must not** be returned"},{"line_number":45,"context_line":"by application code and should only be generated by the HTTP framework in"},{"line_number":46,"context_line":"response to internal errors (for example, unhandled exceptions)."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3afb71cf_e53890a2","line":44,"in_reply_to":"3afb71cf_39193e7a","updated":"2015-06-08 17:26:51.000000000","message":"After reading the 501 clarification in the latest spec, I agree that what we are doing in my second example is incorrect.\n\n\u0027Should not\u0027 is probably OK. Is \u0027framework\u0027 defined anywhere? Maybe this doesn\u0027t mean what I think it means. I find it hard to believe that nobody else is doing what Keystone is doing.","commit_id":"f3d3052138c75289c0c3c355030f1bc19f4a5ba2"},{"author":{"_account_id":12000,"name":"Ian Cordasco","email":"sigmavirus24@gmail.com","username":"sigmavirus24"},"change_message_id":"82fd51c6d9e33fe4778c065ecdf8e89049bfc4a4","unresolved":false,"context_lines":[{"line_number":41,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"These codes represent that the server has generated an error or is"},{"line_number":44,"context_line":"incapable of performing the requested method. They **must not** be returned"},{"line_number":45,"context_line":"by application code and should only be generated by the HTTP framework in"},{"line_number":46,"context_line":"response to internal errors (for example, unhandled exceptions)."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3afb71cf_9519dcd9","line":44,"in_reply_to":"3afb71cf_e53890a2","updated":"2015-06-09 14:22:12.000000000","message":"I don\u0027t think we have any common reference or definitions. For framework I\u0027d consider that webob/pecan/flask/etc.\n\n\u003e I find it hard to believe nobody else is doing what Keystone is doing.\n\nThat\u0027s why Sean called this a \"common mistake\" in his commit message.\n\nAlso, not sure if you\u0027re aware David, but these guidelines don\u0027t go into effect immediately. They\u0027re meant for future API development. There\u0027s nothing that makes you implement these ASAP (unless you\u0027re building something new into your current version of the API and want to).","commit_id":"f3d3052138c75289c0c3c355030f1bc19f4a5ba2"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"43e9a8e1031ec67c684ab02954d65b4e4901bcdb","unresolved":false,"context_lines":[{"line_number":41,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"These codes represent that the server has generated an error or is"},{"line_number":44,"context_line":"incapable of performing the requested method. They **must not** be returned"},{"line_number":45,"context_line":"by application code and should only be generated by the HTTP framework in"},{"line_number":46,"context_line":"response to internal errors (for example, unhandled exceptions)."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3afb71cf_39193e7a","line":44,"in_reply_to":"5afe65bd_068acfbf","updated":"2015-06-08 13:52:18.000000000","message":"David, sounds reasonable to me given the circumstances. do you think we should change the language from \"must not\" to \"should not\"?","commit_id":"f3d3052138c75289c0c3c355030f1bc19f4a5ba2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"efb033e8173d75d89aece4f3af1ebaae1bb6edaf","unresolved":false,"context_lines":[{"line_number":41,"context_line":"~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"These codes represent that the server has generated an error or is"},{"line_number":44,"context_line":"incapable of performing the requested method. They **must not** be returned"},{"line_number":45,"context_line":"by application code and should only be generated by the HTTP framework in"},{"line_number":46,"context_line":"response to internal errors (for example, unhandled exceptions)."},{"line_number":47,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"5afe65bd_068acfbf","line":44,"in_reply_to":"5afe65bd_eb965c93","updated":"2015-06-02 14:52:27.000000000","message":"David, see this patch that describes why returning a 501 Not Implemented is incorrect:\n\nhttps://review.openstack.org/#/c/183456/","commit_id":"f3d3052138c75289c0c3c355030f1bc19f4a5ba2"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"2e3719a1b6b0d0da1cdc0ae90dbfc226390fc10b","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"There are situations where application code may be responsible for"},{"line_number":49,"context_line":"generating a 500 response, for example when adding extra log information"},{"line_number":50,"context_line":"in response to unhandled exceptions. In these cases though, the implementor"},{"line_number":51,"context_line":"should exercise caution to only return these codes in situations where an"},{"line_number":52,"context_line":"error cannot be handled by the server."},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"fa32b979_db68a4f7","line":50,"updated":"2015-06-24 20:28:22.000000000","message":"I don\u0027t quite get why the action of \"adding extra logging info\" would grant a case for returned a 500 error. am I misreading?","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"880649287f0e04dc352fcaeb20a13baa3e02e5fb","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"There are situations where application code may be responsible for"},{"line_number":49,"context_line":"generating a 500 response, for example when adding extra log information"},{"line_number":50,"context_line":"in response to unhandled exceptions. In these cases though, the implementor"},{"line_number":51,"context_line":"should exercise caution to only return these codes in situations where an"},{"line_number":52,"context_line":"error cannot be handled by the server."},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_a8cdbfb8","line":50,"in_reply_to":"ba3cc151_ac0c4143","updated":"2015-07-07 13:45:35.000000000","message":"Done","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"8eedce7454a1054a4259705b4ccfb8d5fa9256bd","unresolved":false,"context_lines":[{"line_number":47,"context_line":""},{"line_number":48,"context_line":"There are situations where application code may be responsible for"},{"line_number":49,"context_line":"generating a 500 response, for example when adding extra log information"},{"line_number":50,"context_line":"in response to unhandled exceptions. In these cases though, the implementor"},{"line_number":51,"context_line":"should exercise caution to only return these codes in situations where an"},{"line_number":52,"context_line":"error cannot be handled by the server."},{"line_number":53,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_ac0c4143","line":50,"in_reply_to":"fa32b979_db68a4f7","updated":"2015-06-29 13:34:08.000000000","message":"i was just using this as an example of a case where it might be acceptable to return a 500. you might have code that catches an exception, logs some extra information, and then re-raises the exception or otherwise propagates the 500 error in the response.\n\nthis example is similar to behavior that is in keystone, and that was the inspiration for adding this as an example.","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"2e3719a1b6b0d0da1cdc0ae90dbfc226390fc10b","unresolved":false,"context_lines":[{"line_number":54,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":55,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":56,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":57,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":58,"context_line":""},{"line_number":59,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":60,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":3,"id":"fa32b979_dbc184e5","line":57,"updated":"2015-06-24 20:28:22.000000000","message":"I think this statement triggers some confusion with 405 and does not make a great job at clarifying that 501 must not be used for \"feature not implemented\".\n\nthis assuming we have consensus on the provisions made in https://review.openstack.org/#/c/183456/","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"880649287f0e04dc352fcaeb20a13baa3e02e5fb","unresolved":false,"context_lines":[{"line_number":54,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":55,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":56,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":57,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":58,"context_line":""},{"line_number":59,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":60,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_6847b71d","line":57,"in_reply_to":"ba3cc151_a73a1acc","updated":"2015-07-07 13:45:35.000000000","message":"Will comment on latest patchset.","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"8eedce7454a1054a4259705b4ccfb8d5fa9256bd","unresolved":false,"context_lines":[{"line_number":54,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":55,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":56,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":57,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":58,"context_line":""},{"line_number":59,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":60,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_a73a1acc","line":57,"in_reply_to":"fa32b979_dbc184e5","updated":"2015-06-29 13:34:08.000000000","message":"true, this is based in some part on the 183456 review. should i leave it out, or is there a way i can clarify this?","commit_id":"4b95d745b1829f03b2464988bd1151c4a1377ee2"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"762bb9743db315532d6eb4e3905468ec64f4916c","unresolved":false,"context_lines":[{"line_number":95,"context_line":"generating a 500 response, for example when adding extra log information"},{"line_number":96,"context_line":"in response to unhandled exceptions. In these cases though, the implementor"},{"line_number":97,"context_line":"should exercise caution to only return these codes in situations where an"},{"line_number":98,"context_line":"error cannot be handled by the server."},{"line_number":99,"context_line":""},{"line_number":100,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":101,"context_line":"does not implement a specific requested behavior. This error is reserved"}],"source_content_type":"text/x-rst","patch_set":5,"id":"ba3cc151_94a18948","line":98,"updated":"2015-07-02 16:43:50.000000000","message":"Replace \"server\" with \"application code\" on this line. You use the word \"server\" above to mean one thing but the meaning is different on this line.","commit_id":"e7b692f14bb72f58a429845bc289817a756269cc"},{"author":{"_account_id":6783,"name":"Nathan Reller","email":"nathan.s.reller@gmail.com","username":"rellerreller"},"change_message_id":"c10fc0025374f09a4b2723497fc8fd0fc2e67091","unresolved":false,"context_lines":[{"line_number":89,"context_line":"These codes represent that the server, or gateway, has encountered an error"},{"line_number":90,"context_line":"or is incapable of performing the requested method. They **should not** be"},{"line_number":91,"context_line":"returned by application code and should only be generated by the HTTP/WSGI"},{"line_number":92,"context_line":"framework, or gateway, in response to internal errors."},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"There are situations where application code may be responsible for"},{"line_number":95,"context_line":"generating a 500 response, for example when adding extra log information"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_175e4a12","line":92,"updated":"2015-07-07 12:57:46.000000000","message":"I think it would be helpful to state what error codes should be returned for application code. Maybe add a link to the section or something.","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":177,"name":"Alex Meade","email":"mr.alex.meade@gmail.com","username":"alex-meade"},"change_message_id":"3ba23955168a3049a8851539a228c8095028b32e","unresolved":false,"context_lines":[{"line_number":89,"context_line":"These codes represent that the server, or gateway, has encountered an error"},{"line_number":90,"context_line":"or is incapable of performing the requested method. They **should not** be"},{"line_number":91,"context_line":"returned by application code and should only be generated by the HTTP/WSGI"},{"line_number":92,"context_line":"framework, or gateway, in response to internal errors."},{"line_number":93,"context_line":""},{"line_number":94,"context_line":"There are situations where application code may be responsible for"},{"line_number":95,"context_line":"generating a 500 response, for example when adding extra log information"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_9bcaa74e","line":92,"updated":"2015-07-06 21:19:09.000000000","message":"yes!","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"f9f69da232158a2baa70964b0d82c198dd84dbb2","unresolved":false,"context_lines":[{"line_number":100,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":101,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":102,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":103,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":104,"context_line":""},{"line_number":105,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":106,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_64768607","line":103,"updated":"2015-07-03 00:45:50.000000000","message":"We have discussed this 501 case on https://review.openstack.org/#/c/181283/ , but it seems difficult to make a consensus on that","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"8c5acaaf856f19a02ea8bc4b70cce5937c5c9c6c","unresolved":false,"context_lines":[{"line_number":100,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":101,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":102,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":103,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":104,"context_line":""},{"line_number":105,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":106,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_bbc9ab7b","line":103,"in_reply_to":"ba3cc151_64768607","updated":"2015-07-06 21:26:40.000000000","message":"good point, i\u0027m not sure how to proceed on this point. it seemed clear from the rfc that 501 was intended for this type of situation.","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"f62feed6ac834c1fb746659a72815cb71094cf7b","unresolved":false,"context_lines":[{"line_number":100,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":101,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":102,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":103,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":104,"context_line":""},{"line_number":105,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":106,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_e807477f","line":103,"in_reply_to":"ba3cc151_bbc9ab7b","updated":"2015-07-07 13:50:47.000000000","message":"I am afraid we do not have yet consensus over 501 semantics.\nI personally tend to agree with this view, but I also have to say that 501 is commonly used for \"feature not implemented\"\n\nHowever, am I the only one feeling there\u0027s a bit of redundancy in having in this file (http.rst) a section on failure codes discussing 5xx errors and then another section on 5xx error codes?","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"e54d22d2407d36730d07556d9544b8ea9a33a5ed","unresolved":false,"context_lines":[{"line_number":100,"context_line":"The 501 response code **should not** be returned to represent that a server"},{"line_number":101,"context_line":"does not implement a specific requested behavior. This error is reserved"},{"line_number":102,"context_line":"for conditions where a server does not implement the requested HTTP method"},{"line_number":103,"context_line":"(GET, HEAD, OPTIONS, PATCH, POST, PUT, TRACE)."},{"line_number":104,"context_line":""},{"line_number":105,"context_line":"The 502, 503, 504, and 505 codes **must not** be returned by application"},{"line_number":106,"context_line":"code as these represent errors, or specialized conditions, that have"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_ef4e66c0","line":103,"in_reply_to":"ba3cc151_e807477f","updated":"2015-07-07 16:00:42.000000000","message":"re: redundancy, are you talking about the section after this for \"Failure Codes\"?\n\ni think the point of this section, \"HTTP Response Codes\", is to cover in general terms all the response codes. it seemed appropriate to have guidance about 5xx here.\n\nre: 501 semantics, it sounds like we might not be able to recommend general advice here. after reading the discussion in the other review linked by Ken\u0027ichi, i\u0027m still not sure what the best course of action is here.\n\ni think we should probably discuss this review in the next api-wg meeting.","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":10215,"name":"Peter Stachowski","email":"peter@tesora.com","username":"peterstac"},"change_message_id":"3bf02d2cbc0c39ebccf4bc1e10d650d71a43704e","unresolved":false,"context_lines":[{"line_number":108,"context_line":"These codes should only be returned by the HTTP/WSGI framework or the"},{"line_number":109,"context_line":"gateway peforming the transport."},{"line_number":110,"context_line":""},{"line_number":111,"context_line":"Failure Codes"},{"line_number":112,"context_line":"~~~~~~~~~~~~~"},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"* If the call results in the OpenStack user exceeding his or her quota, the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_054a89ac","line":111,"range":{"start_line":111,"start_character":0,"end_line":111,"end_character":13},"updated":"2015-07-07 16:35:05.000000000","message":"Maybe this should be changed to \u0027Failure Code Clarification\u0027 (or something similar) instead?","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b1086be865b9e324f88fd1810c37e655447cbd45","unresolved":false,"context_lines":[{"line_number":108,"context_line":"These codes should only be returned by the HTTP/WSGI framework or the"},{"line_number":109,"context_line":"gateway peforming the transport."},{"line_number":110,"context_line":""},{"line_number":111,"context_line":"Failure Codes"},{"line_number":112,"context_line":"~~~~~~~~~~~~~"},{"line_number":113,"context_line":""},{"line_number":114,"context_line":"* If the call results in the OpenStack user exceeding his or her quota, the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"ba3cc151_2db44cf0","line":111,"in_reply_to":"ba3cc151_054a89ac","updated":"2015-07-07 20:20:26.000000000","message":"nice idea, it would definitely improve the intent.","commit_id":"9788002606d522292aa426ecf82eb97ec93e91bc"}]}