)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"b20738330e003ec2776e94fe8d7c75d1dbc14fe1","unresolved":false,"context_lines":[{"line_number":7,"context_line":"Fleshed out the http section a bit more"},{"line_number":8,"context_line":""},{"line_number":9,"context_line":"Added a reference to the Location header, required when creating a new"},{"line_number":10,"context_line":"resource and returning a 201 status code response, and also included the"},{"line_number":11,"context_line":"recommended 405 status code that is used when a valid resource URI is"},{"line_number":12,"context_line":"invoked with an invalid request method."},{"line_number":13,"context_line":""}],"source_content_type":"text/x-gerrit-commit-message","patch_set":4,"id":"da86d52c_7e9bd065","line":10,"updated":"2015-02-12 10:21:14.000000000","message":"Cannot find this in the change to http.rst\n\nIt seems it got merged in another patch, the commit message here should probably be amended.","commit_id":"04cc59c9938cd62f5e7845d5841da2963120ed4f"}],"guidelines/http.rst":[{"author":{"_account_id":8505,"name":"Sam Harwell","email":"sam@tunnelvisionlabs.com","username":"sharwell"},"change_message_id":"a5d45d5680765efc503558afc69d12602adcff54","unresolved":false,"context_lines":[{"line_number":17,"context_line":"~~~~~~~~~~~~~"},{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* If the API call creates a resource on a server, the return code should be"},{"line_number":20,"context_line":"  **201 Created**. The URI of the newly created resource must be included in"},{"line_number":21,"context_line":"  the `Location` header in the response."},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"* If the API call succeeds, but the result of the call has created an"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_530b397c","line":20,"updated":"2014-10-28 21:56:51.000000000","message":"Perhaps change this to \"should be included\", else users might misinterpret inconsistencies which remain for compatibility reasons as bugs that need to be fixed. Also, while I cannot think of a reason right now to omit the `Location` header, I am not absolutely positive it should always be included so \"should be\" is something I can more confidently agree with at this point.","commit_id":"0575fbcaba7caba3619eb240eb00112909668645"},{"author":{"_account_id":8505,"name":"Sam Harwell","email":"sam@tunnelvisionlabs.com","username":"sharwell"},"change_message_id":"e77efee86f06fe42fc54ebe59332246b58fe2e36","unresolved":false,"context_lines":[{"line_number":38,"context_line":"* For badly formatted requests, the return code should be **400 Bad Request**."},{"line_number":39,"context_line":"  Do **not** use **422 Unprocessable Entity**."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the request method is not"},{"line_number":42,"context_line":"  supported for that resource, the return code should be **405 Method Not"},{"line_number":43,"context_line":"  Allowed**. Do **not** use **404 Not Found**. The response should include"},{"line_number":44,"context_line":"  the `Allow` header with the list of accepted request methods for the"}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_f3a6eda9","line":41,"updated":"2014-10-28 21:54:08.000000000","message":"\u003e the request method is not\n\nWould you consider the following wording instead?\n\n\u003e the HTTP method used for the request is not","commit_id":"0575fbcaba7caba3619eb240eb00112909668645"},{"author":{"_account_id":8505,"name":"Sam Harwell","email":"sam@tunnelvisionlabs.com","username":"sharwell"},"change_message_id":"e77efee86f06fe42fc54ebe59332246b58fe2e36","unresolved":false,"context_lines":[{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the request method is not"},{"line_number":42,"context_line":"  supported for that resource, the return code should be **405 Method Not"},{"line_number":43,"context_line":"  Allowed**. Do **not** use **404 Not Found**. The response should include"},{"line_number":44,"context_line":"  the `Allow` header with the list of accepted request methods for the"},{"line_number":45,"context_line":"  resource."},{"line_number":46,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"9aa7fdbe_73b2fde5","line":43,"updated":"2014-10-28 21:54:08.000000000","message":"I believe the sentence about 404 is unnecessary and a minor distraction. It\u0027s implied by the whole rest of this point.","commit_id":"0575fbcaba7caba3619eb240eb00112909668645"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"88c0178dd0396c28f70f200f7fd79b22e452e24d","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* If the API call creates a resource on a server, the return code should be"},{"line_number":20,"context_line":"  **201 Created**. The URI of the newly created resource should be included in"},{"line_number":21,"context_line":"  the `Location` header in the response."},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"* If the API call succeeds, but the result of the call has created an"},{"line_number":24,"context_line":"  asynchronous task that will need to be polled to get completion or state"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_fc77b9d1","line":21,"updated":"2014-12-04 10:48:54.000000000","message":"I am honestly never been too convinced on the need to make a 201 mandatory.\nI think 201 becomes confusing for operations which create multiple resources or which create a resource and at the same time update another one. Also, another thing I\u0027ve noticed is that this generates confusion when asynchronous patterns are involved. For instance, let\u0027s consider the case of instance creation.\nIt\u0027s asynchronous so when the calls returns the instance does not exist on the hypervisor and the request for processing has been accepted, so it is a 202.\nHowever, the logical resource, the one that you can list when you do a GET on the API has been created, so 201 would also be a reasonable error code.\nSo I think that we either mandate a 201 for all operations that actually create a logical resource (ie: a resource that exist in the API once you do a get on it), regardless of the sync/async pattern of the operation or we just stop using 201 - and use 200 for synchronous operation and 202 for async.","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"c0dcb1d4e181628d25275145fbad7ef058b3a572","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"* If the API call creates a resource on a server, the return code should be"},{"line_number":20,"context_line":"  **201 Created**. The URI of the newly created resource should be included in"},{"line_number":21,"context_line":"  the `Location` header in the response."},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"* If the API call succeeds, but the result of the call has created an"},{"line_number":24,"context_line":"  asynchronous task that will need to be polled to get completion or state"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_76d11d56","line":21,"in_reply_to":"5a890539_fc77b9d1","updated":"2014-12-04 15:49:21.000000000","message":"Salvatore, note that we are saying \"should\", not \"must\". The distinction is important, this is a recommendation, not a regulation.\n\nIn your example of async instance creation, if the instance is created immediately then the operation is not asynchronous, it should return 201 and the URL of the new instance resource. The 202 should only be returned if the new resource does not exist and will be created in a background task. I don\u0027t see any confusion there.\n\nAlso, do not get wrapped up in how things work today. This is not intended to described today\u0027s behaviors. If an instance is created, but nova still returns a 202 that is fine, but is not an appropriate use of REST.","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":8505,"name":"Sam Harwell","email":"sam@tunnelvisionlabs.com","username":"sharwell"},"change_message_id":"df7e5efbdf5ab4562e0772829683fe1cc4f70181","unresolved":false,"context_lines":[{"line_number":38,"context_line":"* For badly formatted requests, the return code should be **400 Bad Request**."},{"line_number":39,"context_line":"  Do **not** use **422 Unprocessable Entity**."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."}],"source_content_type":"text/x-rst","patch_set":3,"id":"9aa7fdbe_63e78aad","line":41,"updated":"2014-10-29 03:32:53.000000000","message":"Forgot to mention earlier, we should indicate somewhere that this applies only to authenticated calls. For example, here we could change \"If a call...\" to \"If a properly authenticated call...\"","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"3afa362eec041f7ace2fabdd6fe4a72f5c3cdb66","unresolved":false,"context_lines":[{"line_number":38,"context_line":"* For badly formatted requests, the return code should be **400 Bad Request**."},{"line_number":39,"context_line":"  Do **not** use **422 Unprocessable Entity**."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_132b7434","line":41,"in_reply_to":"5a890539_5cfd2db0","updated":"2014-11-18 17:53:38.000000000","message":"+1 for @Eoghan.\n\nSaying it\u0027s only for authenticated calls is irrelevant, we have to assume that otherwise we have to add that \"if a properly authenticated call... \" for almost every single bullet point of this guideline.\n\nThere\u0027s another error that is returned by unauthenticated calls (which is HTTP 401) , we can explain the not properly authenticated call there.","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":2284,"name":"Eoghan Glynn","email":"eglynn@redhat.com","username":"eglynn"},"change_message_id":"5ef3d25488f4f9931c084ce5ceb04dc0048d0134","unresolved":false,"context_lines":[{"line_number":38,"context_line":"* For badly formatted requests, the return code should be **400 Bad Request**."},{"line_number":39,"context_line":"  Do **not** use **422 Unprocessable Entity**."},{"line_number":40,"context_line":""},{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_5cfd2db0","line":41,"in_reply_to":"9aa7fdbe_63e78aad","updated":"2014-11-17 22:51:14.000000000","message":"Could we make the authenticated call aspect implicit, with the assumption that auth is always applied first on the dispatch patch before any further validation of the request?","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":5292,"name":"Christopher Yeoh","email":"cbkyeoh@gmail.com","username":"cyeoh-0"},"change_message_id":"fbd8efc6ce6c136884d611331e718629d8ede2ba","unresolved":false,"context_lines":[{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"HTTP Methods"},{"line_number":47,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_cb7731d3","line":44,"updated":"2014-11-12 05:33:36.000000000","message":"So the part about requiring an allow header with a list of accepted request methods is a bit of a pain to implement, at least in Nova. Which is why we didn\u0027t end up doing it. We just return a 404. So I\u0027d prefer that this isn\u0027t ever a required part, ok with a recommendation.","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"3afa362eec041f7ace2fabdd6fe4a72f5c3cdb66","unresolved":false,"context_lines":[{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"HTTP Methods"},{"line_number":47,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_9393e45b","line":44,"in_reply_to":"5a890539_1c700571","updated":"2014-11-18 17:53:38.000000000","message":"@Eoghan for the off-topic question. I asked that in in Paris and the answer was no.\n\n@Christopher, that\u0027s fine that\u0027s why the guideline say \"should\" and not \"have to\" or \"must\"","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":970,"name":"Dean Troyer","email":"dtroyer@gmail.com","username":"dtroyer"},"change_message_id":"4ee2fb6af8149421b19cb77e6a4b8b62a7833b31","unresolved":false,"context_lines":[{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"HTTP Methods"},{"line_number":47,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_bc677ae9","line":44,"in_reply_to":"5a890539_9393e45b","updated":"2014-11-20 17:05:53.000000000","message":"Eoghan, I agree with Lucas, we\u0027re dealing with specs and design and process here, not implementation.  Just as one of the goals is to facilitate multiple client implementations in multiple languages, we should stay in a position to do the same with servers, should non-python services ever become a thing in OpenStack.\n\nAll that said, I can see where an Appendix with pointers to implementation examples would be useful.","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"},{"author":{"_account_id":2284,"name":"Eoghan Glynn","email":"eglynn@redhat.com","username":"eglynn"},"change_message_id":"5ef3d25488f4f9931c084ce5ceb04dc0048d0134","unresolved":false,"context_lines":[{"line_number":41,"context_line":"* If a call is made to a known resource URI, but the HTTP method used for the"},{"line_number":42,"context_line":"  request is not supported for that resource, the return code should be **405"},{"line_number":43,"context_line":"  Method Not Allowed**. The response should include the `Allow` header with"},{"line_number":44,"context_line":"  the list of accepted request methods for the resource."},{"line_number":45,"context_line":""},{"line_number":46,"context_line":"HTTP Methods"},{"line_number":47,"context_line":"------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a890539_1c700571","line":44,"in_reply_to":"5a890539_cb7731d3","updated":"2014-11-17 22:51:14.000000000","message":"As it happens pecan will try to populate the Allow header automagically:\n\n  https://github.com/stackforge/pecan/blob/master/pecan/core.py#L693\n\nOff-topic, but is this API WG ever intended to get into the realm of making recommendations on preferred API frameworks to use?","commit_id":"96490083bfefba101d1bdda91e8a19fd58f57f58"}]}