)]}'
{"/COMMIT_MSG":[{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"b405fae5906ce420dcb453d5f2da483ff15f9973","unresolved":false,"context_lines":[{"line_number":7,"context_line":"Add advice on when to use POST or PUT in create"},{"line_number":8,"context_line":""},{"line_number":9,"context_line":"This replays the decision made in the API-WG meeting at:"},{"line_number":10,"context_line":"http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-05-07-16.01.log.html#l-200"},{"line_number":11,"context_line":""},{"line_number":12,"context_line":"Change-Id: Iabd21b97466013645cd7520b3aa315b9544f6aa3"}],"source_content_type":"text/x-gerrit-commit-message","patch_set":7,"id":"3a50d1a3_a64f35bd","line":10,"updated":"2015-07-27 06:43:18.000000000","message":"pedant note: It\u0027s better to summarize the discussion on the commit message. This commit message is going to stay in the repo log for ages. The page on eavesdrop.openstack.org might as well move in the meanwhile","commit_id":"3fff122189c6aa57bbc77ee4293f4faee84bb247"}],"guidelines/http.rst":[{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"c0e2f2728db05dff4f5a9875d990259c0f776179","unresolved":false,"context_lines":[{"line_number":68,"context_line":""},{"line_number":69,"context_line":"That is, if the id of the resource being created is known, use PUT and PUT to"},{"line_number":70,"context_line":"the correct URI of the resource. Otherwise, use POST and POST to a more generic"},{"line_number":71,"context_line":"URI which will respond with the URI of the resource."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"Conveying error/fault information to the end user"},{"line_number":74,"context_line":"-------------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a0c5dc1_db936aa2","line":71,"updated":"2015-05-12 20:54:09.000000000","message":"The API design of Nova is based on the above description, so the description is almost good for me. However, the combination of PUT and URI without resource-id is used for bulk update on the other REST API services.\n\nIf clients want to apply the same change to multiple resources, they can use the combination if the server supports. but the above description doesn\u0027t allow to implement this feature on OpenStack projects.\n\nSo soft -1 now for clarifying this point and its reason.","commit_id":"94941c79c74d9d73d7566923bd05f6aa251707cf"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"4cdc3946a6f663c482ee687aba62dd61f6aa68e8","unresolved":false,"context_lines":[{"line_number":68,"context_line":""},{"line_number":69,"context_line":"That is, if the id of the resource being created is known, use PUT and PUT to"},{"line_number":70,"context_line":"the correct URI of the resource. Otherwise, use POST and POST to a more generic"},{"line_number":71,"context_line":"URI which will respond with the URI of the resource."},{"line_number":72,"context_line":""},{"line_number":73,"context_line":"Conveying error/fault information to the end user"},{"line_number":74,"context_line":"-------------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":1,"id":"9a0c5dc1_5bcc1a35","line":71,"in_reply_to":"9a0c5dc1_db936aa2","updated":"2015-05-12 21:07:34.000000000","message":"Can you give me a pointer to an example of the nova usage you are describing?\n\nIt sounds like you are saying the PUT is being made to a URI that represents a collection of some kind of resource and the PUT is changing those several.\n\nIf I\u0027ve understood you, that is incorrect. That should almost certainly be a POST.\n\nBut that\u0027s okay: These guidelines aren\u0027t supposed to reflect the way things are and tools are not required to follow them strictly. They are aspirational guidelines, not required guidelines.\n\nWhat we don\u0027t want to do is write guidelines that\n\n* are somewhat less than correct\n* are constantly making caveats about some existing tools that don\u0027t currently match with the guidelines\n\nDoing either would muddy the guidelines greatly.","commit_id":"94941c79c74d9d73d7566923bd05f6aa251707cf"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"6c4595bb8c5d02cfb40a299eaf5165d6aaa0f375","unresolved":false,"context_lines":[{"line_number":77,"context_line":""},{"line_number":78,"context_line":"When multiple resources are targeted for update in one request (for example to"},{"line_number":79,"context_line":"apply the same change in state to multiple resources) the request method should"},{"line_number":80,"context_line":"be POST."},{"line_number":81,"context_line":""},{"line_number":82,"context_line":"Conveying error/fault information to the end user"},{"line_number":83,"context_line":"-------------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a0c5dc1_e107807f","line":80,"updated":"2015-05-13 15:31:09.000000000","message":"IMO, HTTP methods are\n\n POST - Create\n GET - Read\n PUT - Update\n DELETE - Delete\n\nfor CRUD operations. and these meanings would be independent from resource URIs. Resource URIs are just targets, so the above description seems unreasonable for me.\nThis is just my feeling, and I will try another patch for clarifying my thinking.","commit_id":"b5e372b04c1ab60dd4c72f09a72940230fd9f351"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"037da47ed25c8b162dc34de810893a2ea04ceff2","unresolved":false,"context_lines":[{"line_number":77,"context_line":""},{"line_number":78,"context_line":"When multiple resources are targeted for update in one request (for example to"},{"line_number":79,"context_line":"apply the same change in state to multiple resources) the request method should"},{"line_number":80,"context_line":"be POST."},{"line_number":81,"context_line":""},{"line_number":82,"context_line":"Conveying error/fault information to the end user"},{"line_number":83,"context_line":"-------------------------------------------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a016987_858a0ebe","line":80,"in_reply_to":"9a0c5dc1_e107807f","updated":"2015-05-15 20:23:28.000000000","message":"Ken\u0027ichi I think you and cdent are actually pretty close in thinking.\n\nThe important difference between PUT and POST in HTTP is the following:\n\nPOST /to/some/uri\n...\nreturns references /to/some/other/uri\n\nPUT /to/some/uri - update a resource\nGET /to/some/uri - get that resource\n\nBasically POSTed resources won\u0027t be to the same URI as the GET of the objects created. PUT will be, because the thing already exists. So the multiple update has to be done as a POST.\n\nI think if there was a broader baseline for the HTTP methods it would make more sense.\n\nPOST/GET/PUT/DELETE \u003d\u003e CRUD is an approximate, not an exact, mapping, that works 90% of the time, but there are specific URI semantics that HTTP expects so multiple update will be a POST.","commit_id":"b5e372b04c1ab60dd4c72f09a72940230fd9f351"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"2ee546b99ed4cde47b2e2a45b1da983ef6db10a2","unresolved":false,"context_lines":[{"line_number":65,"context_line":"creating new resources. POST should be used when the URI of the resulting resource"},{"line_number":66,"context_line":"is different from the URI to which the request was made and results in the resource"},{"line_number":67,"context_line":"having an identifier (the URI) that the server generated. In the OpenStack environment"},{"line_number":68,"context_line":"this is the common case. PUT should be used for resource creation when the URI to which"},{"line_number":69,"context_line":"the request is made and the URI of the resulting resource is the same."},{"line_number":70,"context_line":""},{"line_number":71,"context_line":"That is, if the id of the resource being created is known, use PUT and PUT to"}],"source_content_type":"text/x-rst","patch_set":4,"id":"5afe65bd_33438f44","line":68,"updated":"2015-06-03 17:56:51.000000000","message":"the previous 4 lines are causing issues due to length","commit_id":"ebcf93f2e1521dc3453eb279186fa566c405dd17"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"a1af2d0ba7d1d093a0aa0914e478ee8f5c6a17e9","unresolved":false,"context_lines":[{"line_number":58,"context_line":"**TODO**: Provide guidance on what HTTP methods (PUT/POST/PATCH/DELETE, etc)"},{"line_number":59,"context_line":"should always be supported, and which should be preferred."},{"line_number":60,"context_line":""},{"line_number":61,"context_line":"POST versus PUT for create"},{"line_number":62,"context_line":"~~~~~~~~~~~~~~~~~~~~~~~~~~"},{"line_number":63,"context_line":""},{"line_number":64,"context_line":"There can be confusion on when to use POST or PUT in the specific instance of"}],"source_content_type":"text/x-rst","patch_set":5,"id":"fa32b979_1bdfecd6","line":61,"updated":"2015-06-24 20:23:42.000000000","message":"https://review.openstack.org/#/c/189738/1/guidelines/http.rst kind of duplicates this.\n\nAs the latins said \"repetita iuvant\", but in this case the same thing would be stated twice in the same section.","commit_id":"8d06e9b0da34d4d64591e722eaf17944fdbf72a0"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"77c24c00d6da08c7166830314c7abc054d64703b","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_aec9ea5a","line":133,"updated":"2015-07-22 21:20:42.000000000","message":"[[citation needed]]\n\nor you can specify that this requirement is being imposed by the API WG.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"9f2264f0702ac839b0b8f10b37611743175ae6e6","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_e7fdd4b1","line":133,"in_reply_to":"3a50d1a3_6759c434","updated":"2015-07-22 22:05:33.000000000","message":"I am happy to see plenty of references, but on the other hand I also do not see a strong reason for linking to every relevant subsection of the RFCs composing HTTP/1.1\n\nThis is a guideline for API developers, not a parliamentary bill after all.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f9c13cccc669ec78703d8ceeddc46fee8953b687","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_d0e07a2b","line":133,"in_reply_to":"3a50d1a3_6759c434","updated":"2015-07-23 08:08:18.000000000","message":"This section has nothing to say about multiple URIs or asymmetry in request and response representations. Those would be topics for other patchsets. If we tried to cover everything in one go we\u0027d never be done because we\u0027d be arguing over each distinct point limiting others such that nothing would ever get through.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f9c13cccc669ec78703d8ceeddc46fee8953b687","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_f03fb6b1","line":133,"in_reply_to":"3a50d1a3_aec9ea5a","updated":"2015-07-23 08:08:18.000000000","message":"As stated in the commit message this is a recapitulation of discussion that happened at a working group meeting, wherein it was decided that it was useful to capture some common wisdom related to POST and PUT when doing create. Two things about that:\n\n* it\u0027s common wisdom that\u0027s generally agreed upon by a group of experienced people so not specifically articulated in any spec anywhere\n* it\u0027s a _guideline_ not a requirement, thus the \"should\" instead of \"must\" that\u0027s all over the place\n\nDo you think it would be useful to interject something before the second sentence which effectively says: \"Working group members have agreed that a good rule of thumb is the following:\"","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"e772cc1fa2a806fcacb010af3994dbf9abd7dbf7","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_6759c434","line":133,"in_reply_to":"3a50d1a3_aec9ea5a","updated":"2015-07-22 21:49:11.000000000","message":"to be clear, I think it\u0027d be useful to refer to the relevant section and ideally paragraph because, as the intro states, the RFC is quite large.\n\nIt might also be useful to have some guidance about resources with multiple URIs. EG you should PUT to /neutron/v1/simple_network (assuming you can subsequently GET that URI) despite that creating a resource also accessible at EG /neutron/v1/networks/\u003cuuid\u003e.\n\nI don\u0027t see anything in section 9.6 about the body of a PUT having to exactly match the eventual resource but it could be elsewhere.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":8688,"name":"Alexis Lee","email":"openstack@lxsli.co.uk","username":"lxsli"},"change_message_id":"3978a307fe87da8edabec6f7506db043b9397178","unresolved":false,"context_lines":[{"line_number":130,"context_line":""},{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_d45615cd","line":133,"in_reply_to":"3a50d1a3_f03fb6b1","updated":"2015-07-23 14:42:49.000000000","message":"Having read the RFC (again) - no, you don\u0027t need to add that. Section 9.6 para starting \"The fundamental difference\" is pretty clear and your advice matches. My only excuse is I\u0027m at the Nova midcycle and was clearly sleep-typing.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"ed7cb40c2d2a154df83520a103452a90ddc40919","unresolved":false,"context_lines":[{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a41bdd9_ecc30437","line":134,"updated":"2015-07-17 13:41:01.000000000","message":"s/having/have/","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"c8a7138761ff82c5d796acb09839a00d7d520ec3","unresolved":false,"context_lines":[{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_2698051b","line":134,"in_reply_to":"3a50d1a3_30df5e3b","updated":"2015-07-27 06:42:47.000000000","message":"I guess it\u0027s fine. I probably lost that among the other comments.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f9c13cccc669ec78703d8ceeddc46fee8953b687","unresolved":false,"context_lines":[{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_30df5e3b","line":134,"in_reply_to":"3a50d1a3_c7f1b896","updated":"2015-07-23 08:08:18.000000000","message":"Yeah, for this subsection we\u0027re only talking about one single thing: when POST and PUT are used in creating resources. Other guidelines can capture when POST is used for actions (and whether it should do so at all).\n\nIs the opening sentence, which includes \"in the specific instance of creating new resources\" not a clear enough signal that that guideline is limited to a specific context?","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"9f2264f0702ac839b0b8f10b37611743175ae6e6","unresolved":false,"context_lines":[{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_c7f1b896","line":134,"in_reply_to":"9a41bdd9_aa787cf9","updated":"2015-07-22 22:05:33.000000000","message":"English wording aside there is something that is probably not entirely correct.\n\nPOST is used also for \"actions\" (e.g: http://developer.openstack.org/api-ref-compute-v2.html#rebootServer). But this operation does not create any resource. Also, it returns an empty response.\n\nFrom what I gather this is a completely legit in RESTful APIs, and does not violate any part of the HTTP RFCs. But it seems this paragraph does not capture it.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"96ea7d7a0257eb0afba90c6907b85d26c1c826a5","unresolved":false,"context_lines":[{"line_number":131,"context_line":"* There can also be confusion on when to use **POST** or **PUT** in the"},{"line_number":132,"context_line":"  specific instance of creating new resources. **POST** should be used when"},{"line_number":133,"context_line":"  the URI of the resulting resource is different from the URI to which the"},{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."}],"source_content_type":"text/x-rst","patch_set":6,"id":"9a41bdd9_aa787cf9","line":134,"in_reply_to":"9a41bdd9_ecc30437","updated":"2015-07-17 14:18:35.000000000","message":"Nope, if you remove the extraneous words and compare:\n\n\"X results in the resource having an identifier.\"\n\n\"X results in the resource have an identifier.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"9f2264f0702ac839b0b8f10b37611743175ae6e6","unresolved":false,"context_lines":[{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."},{"line_number":138,"context_line":""},{"line_number":139,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":140,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_a7958c33","line":137,"updated":"2015-07-22 22:05:33.000000000","message":"Talking about wording... the last sentence might be easier to understand if we say that PUT must always be used with a resource identifier (eg.: PUT /meh_project/v1/meh_resource/meh_id, and its outcome might result in the resource being created if it does not already exist. Whether this should result in resource creation or error is up to the application.\n\nAs a side note, if PUT ends up creating a resource, should it return 201? (it normally returns 200 or 204)","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"f9c13cccc669ec78703d8ceeddc46fee8953b687","unresolved":false,"context_lines":[{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."},{"line_number":138,"context_line":""},{"line_number":139,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":140,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_f0933659","line":137,"in_reply_to":"3a50d1a3_a7958c33","updated":"2015-07-23 08:08:18.000000000","message":"There\u0027s a separate guidelines about response codes.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"c8a7138761ff82c5d796acb09839a00d7d520ec3","unresolved":false,"context_lines":[{"line_number":134,"context_line":"  request was made and results in the resource having an identifier (the URI)"},{"line_number":135,"context_line":"  that the server generated. In the OpenStack environment this is the common"},{"line_number":136,"context_line":"  case. **PUT** should be used for resource creation when the URI to which the"},{"line_number":137,"context_line":"  request is made and the URI of the resulting resource is the same."},{"line_number":138,"context_line":""},{"line_number":139,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":140,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_86b0f98c","line":137,"in_reply_to":"3a50d1a3_f0933659","updated":"2015-07-27 06:42:47.000000000","message":"great, I\u0027ll check there.","commit_id":"7ca54c527a4c90fc319fc5caa47bb3a7d5388971"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"18865ec49c2dafa4e617a1d2c71698772482ffae","unresolved":false,"context_lines":[{"line_number":150,"context_line":"  request is made and the URI of the resulting resource is the same."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_3e462550","line":153,"updated":"2015-08-13 16:25:33.000000000","message":"remove \"correct\" -- putting it there makes readers wonder if there\u0027s a situation where you would do things incorrectly.","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"28be3d702dad8c1459352ce57eac26906e6f9eb7","unresolved":false,"context_lines":[{"line_number":150,"context_line":"  request is made and the URI of the resulting resource is the same."},{"line_number":151,"context_line":""},{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"fa1b9901_0b8f6224","line":153,"in_reply_to":"1a4dcd0f_3e462550","updated":"2015-08-17 15:12:04.000000000","message":"that makes sense","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"8948a6889d3a18842371a00900c0fc9faf719c7b","unresolved":false,"context_lines":[{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* GET method"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_2032005f","line":155,"updated":"2015-08-11 15:07:25.000000000","message":"I think it\u0027s worth mentioning that PUT is expected to be idempotent, i.e. 2 PUTs in a row should result in the same thing as one PUT.","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"18865ec49c2dafa4e617a1d2c71698772482ffae","unresolved":false,"context_lines":[{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* GET method"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_be7eb568","line":155,"updated":"2015-08-13 16:25:33.000000000","message":"There should be an explanation of how the server will respond with the new URI... in the body of the response? I thought it was supposed to be in the Location header of the response and the code is 201 Created.\n\nAlso, should PUT return 201 Created or 200 OK?","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"84580a792835aff088252433b06da8e808db8e8f","unresolved":false,"context_lines":[{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* GET method"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_678a39c1","line":155,"in_reply_to":"1a4dcd0f_2032005f","updated":"2015-08-12 09:15:30.000000000","message":"good point, +1","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":15168,"name":"Kirill Zaitsev","email":"k.zaitsev@me.com","username":"kzaitsev"},"change_message_id":"5e451d1c0e2ad51bcf06659216d8066891434e1d","unresolved":false,"context_lines":[{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* GET method"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_fef414d0","line":155,"in_reply_to":"1a4dcd0f_be7eb568","updated":"2015-08-14 10:42:37.000000000","message":"That\u0027s an interesting point, actually. I feel, that PUT requests might return 200 or 202 (in case update is made asynchronously), if we update a single resource.\n\nIf we update the whole collection with PUT response might be 201 (because new instances were created) or 202.\n\nI feel, that it\u0027s worth clarifying this here.","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"28be3d702dad8c1459352ce57eac26906e6f9eb7","unresolved":false,"context_lines":[{"line_number":152,"context_line":"  That is, if the id of the resource being created is known, use **PUT** and"},{"line_number":153,"context_line":"  **PUT** to the correct URI of the resource. Otherwise, use **POST** and"},{"line_number":154,"context_line":"  **POST** to a more generic URI which will respond with the new URI of the"},{"line_number":155,"context_line":"  resource."},{"line_number":156,"context_line":""},{"line_number":157,"context_line":"* GET method"},{"line_number":158,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"fa1b9901_cbaaca85","line":155,"in_reply_to":"1a4dcd0f_fef414d0","updated":"2015-08-17 15:12:04.000000000","message":"i agree with the comments about idempotence, but i think the return code comments might be better served with a new change to the \"Response Codes\" section. i think it\u0027s good advice but this review is specifically about when to use put vs post, not necessarily on all the intricacies of using the method.","commit_id":"a83a1e553c1f9507a83592e227772bd456231858"}]}