)]}'
{"guidelines/uri.rst":[{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"a4f918b8717c64ab07244fa34e19caf833ea411a","unresolved":false,"context_lines":[{"line_number":57,"context_line":"* Since a single URI identifies a single resource it is also useful"},{"line_number":58,"context_line":"  for two more things to be kept true when building services:"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"  * Any resource should only have one URI. Where possible don\u0027t provide"},{"line_number":61,"context_line":"    multiple ways to reference the same thing. Use HTTP redirects to"},{"line_number":62,"context_line":"    resolve indirect requests to the correct canonical URI and"},{"line_number":63,"context_line":"    content negotiation to request different representations."}],"source_content_type":"text/x-rst","patch_set":2,"id":"9abb7d3a_20a64f53","line":60,"updated":"2016-06-03 18:10:05.000000000","message":"\"Where possible, do not...\"","commit_id":"59e3145bd05b0911df943460994179918a984b72"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"de6a927f29b572c1a1617bd80d43b1ded1db115b","unresolved":false,"context_lines":[{"line_number":57,"context_line":"* Since a single URI identifies a single resource it is also useful"},{"line_number":58,"context_line":"  for two more things to be kept true when building services:"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"  * Any resource should only have one URI. Where possible don\u0027t provide"},{"line_number":61,"context_line":"    multiple ways to reference the same thing. Use HTTP redirects to"},{"line_number":62,"context_line":"    resolve indirect requests to the correct canonical URI and"},{"line_number":63,"context_line":"    content negotiation to request different representations."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7aa08908_7c8322cd","line":60,"in_reply_to":"9abb7d3a_20a64f53","updated":"2016-06-06 10:50:36.000000000","message":"Done","commit_id":"59e3145bd05b0911df943460994179918a984b72"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"d6af7d7dd2b399f6ae56075791cd2cdf76be8f3b","unresolved":false,"context_lines":[{"line_number":23,"context_line":"opportunity nor reason to exert control over `scheme` and"},{"line_number":24,"context_line":"`authority`."},{"line_number":25,"context_line":""},{"line_number":26,"context_line":"What follows will concern itself solely with the `path` and `query`."},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Things Worth Knowing"},{"line_number":29,"context_line":"--------------------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7aa08908_c53c8095","line":26,"updated":"2016-06-13 15:14:04.000000000","message":"++ great intro","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":4,"name":"Dolph Mathews","email":"dolph.mathews@gmail.com","username":"dolph"},"change_message_id":"d6af7d7dd2b399f6ae56075791cd2cdf76be8f3b","unresolved":false,"context_lines":[{"line_number":120,"context_line":"  `query` to augment the existing collection URI to indicate the"},{"line_number":121,"context_line":"  desire for more detail [#non-normative]_::"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"    GET /os-cells?details\u003dtrue"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":""},{"line_number":126,"context_line":".. rubric:: Footnotes"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7aa08908_e5dd3c15","line":123,"updated":"2016-06-13 15:14:04.000000000","message":"Booleans in query strings are touchy subjects, IMO, because the value is completely unstandardized and entirely unnecessary (beyond the historical convention of using HTML form encoding, which is not a use case for our APIs). As a result, a lot of edge cases like `?details\u003dtrue`, `?details\u003d1`, `?details\u003dt`, `?details\u003dfalse`, all need to be handled to uniformly support arbitrary client behaviors, when intent could be made much more clear by not documenting, supporting, or acknowledging the value and instead supporting either `?details` and `?nodetails` instead (whichever reflects the non-default, opt-in behavior).\n\nAll that to say, that while this example certainly improves on `GET /os-cells/details`, I\u0027d hesitate to support it as a well-rounded example overall.","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"8fd57f1d620ed39cd054ddc2c114819b8d3d6f7a","unresolved":false,"context_lines":[{"line_number":120,"context_line":"  `query` to augment the existing collection URI to indicate the"},{"line_number":121,"context_line":"  desire for more detail [#non-normative]_::"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"    GET /os-cells?details\u003dtrue"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":""},{"line_number":126,"context_line":".. rubric:: Footnotes"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_fadfb0d3","line":123,"in_reply_to":"1aa78d24_847913ff","updated":"2016-07-11 21:11:36.000000000","message":"I was thinking out loud regarding the edge cases that dolphm pointed out. IMO it would be inconsistent to have query parameters without values; since, at the least, on most GETs, we have search filters and sorting implemented with query parameters...","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":5707,"name":"Henry Nash","email":"henryn@linux.vnet.ibm.com","username":"henry-nash"},"change_message_id":"1aba58796cfeee705c55e8b62d1fa5d6e71d980e","unresolved":false,"context_lines":[{"line_number":120,"context_line":"  `query` to augment the existing collection URI to indicate the"},{"line_number":121,"context_line":"  desire for more detail [#non-normative]_::"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"    GET /os-cells?details\u003dtrue"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":""},{"line_number":126,"context_line":".. rubric:: Footnotes"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_93113707","line":123,"in_reply_to":"1aa78d24_fadfb0d3","updated":"2016-07-11 22:25:28.000000000","message":"I think the only question is whether you want to represent booleans as a key-less attribute, to avoid the issue of having to argue what values repent true and false. I.e., as dolph, says ?details and ?nodetails, or ?enabled and ?disabled etc. Unfortunately in keystone we are in a bit of pickle...and we have examples of both methods....and we\u0027d really like to settle on one...which would be what we would recommend cross-project","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":5707,"name":"Henry Nash","email":"henryn@linux.vnet.ibm.com","username":"henry-nash"},"change_message_id":"f0ee7a977b8ba3c5a5aa081e8ee3e8b127a29eb9","unresolved":false,"context_lines":[{"line_number":120,"context_line":"  `query` to augment the existing collection URI to indicate the"},{"line_number":121,"context_line":"  desire for more detail [#non-normative]_::"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"    GET /os-cells?details\u003dtrue"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":""},{"line_number":126,"context_line":".. rubric:: Footnotes"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_847913ff","line":123,"in_reply_to":"7aa08908_0258e82f","updated":"2016-07-11 11:43:18.000000000","message":"Goutham - I\u0027m not quite clear from your answer whether you are agreeing with dolphm that it would be better to have key-only attributes instead of true booleans as query parameters? Or are you arguing for a specific rule for what you can and can\u0027t specify for true/false of a boolean?","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":16643,"name":"Goutham Pacha Ravi","email":"gouthampravi@gmail.com","username":"gouthamr"},"change_message_id":"1dc29d061e9f37f8ebe1da7b5cc8f77e8c0ad4cb","unresolved":false,"context_lines":[{"line_number":120,"context_line":"  `query` to augment the existing collection URI to indicate the"},{"line_number":121,"context_line":"  desire for more detail [#non-normative]_::"},{"line_number":122,"context_line":""},{"line_number":123,"context_line":"    GET /os-cells?details\u003dtrue"},{"line_number":124,"context_line":""},{"line_number":125,"context_line":""},{"line_number":126,"context_line":".. rubric:: Footnotes"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7aa08908_0258e82f","line":123,"in_reply_to":"7aa08908_e5dd3c15","updated":"2016-06-14 23:28:18.000000000","message":"This particular format made its way into the home grown wsgi layer of nova, and got inherited by all the projects that forked from it and still use the layer.. So, in manila, we\u0027ve 8 API methods that are /some/resource/detail \n\nBut I agree, we can stop doing this going forward, clients can be told that the server does not normalize variations of ?details\u003dtrue, such as the ones noted.. `?details\u003d1`, `?details\u003dt` and must check the value of \"details\" if true or false rather than just check on key?","commit_id":"b5073a1e715d2625de908977022dbc5ffd8d6128"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"eac694d4cbf8278e49ca3a72a9b5e43ab1c83a05","unresolved":false,"context_lines":[{"line_number":78,"context_line":""},{"line_number":79,"context_line":"* It is often the case that an API will have URIs that"},{"line_number":80,"context_line":"  represent collections for resources and individual members of that"},{"line_number":81,"context_line":"  collection in a hierarchy. For example [#non-normative]_::"},{"line_number":82,"context_line":""},{"line_number":83,"context_line":"    GET /birds"},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"3ac371cc_c3337712","line":81,"updated":"2016-08-18 16:37:37.000000000","message":"Does this point about collections obviate the need for http://specs.openstack.org/openstack/api-wg/guidelines/representation_structure.html or should it link to it from here?","commit_id":"0f150e1b0d17d2ee9250a759071fcaedba2af962"}]}