)]}'
{"guidelines/api-docs.rst":[{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"b54851a7d4439200f5f48ebbfa7e1d1d329e11d0","unresolved":false,"context_lines":[{"line_number":26,"context_line":"REST API and what it provides as a service."},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Documentation should also offer information about the concepts for each"},{"line_number":29,"context_line":"resource, such as server status or volume status. "},{"line_number":30,"context_line":""},{"line_number":31,"context_line":"Documentation should provide a discussion about the consistency model the"},{"line_number":32,"context_line":"service provides and synchronous or asynchronous behavior for certain methods."}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa1b9901_87975eeb","line":29,"updated":"2015-08-19 22:19:11.000000000","message":"whitespace","commit_id":"ba4ee8e60a91e6d7f7062d183e5b40cf5eb0fabf"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"579d218fcd972d41767ffe28aec3e30af09b7cb8","unresolved":false,"context_lines":[{"line_number":12,"context_line":""},{"line_number":13,"context_line":"- verb (GET/PUT/POST/PATCH/HEAD/DELETE)"},{"line_number":14,"context_line":"- Method (HTTP resource)"},{"line_number":15,"context_line":"- Requests including parameter, type and description including whether it\u0027s optional"},{"line_number":16,"context_line":"- Responses including parameter, type and description"},{"line_number":17,"context_line":"- Example request body"},{"line_number":18,"context_line":"- Example response body"}],"source_content_type":"text/x-rst","patch_set":2,"id":"fa1b9901_4fb423f1","line":15,"updated":"2015-08-25 08:56:49.000000000","message":"These three lines above are not quite right, especially when talking in a our usual domain of sorta-RESTful. Maybe:\n\n- Method (GET [...])\n- Resource (URL)\n- Request parameters, media-type (for accept or content-type headers)","commit_id":"e20bbbeba4d65460ff4e2cef54bde70207ebbb3d"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"bf96f3544f43c3f4cb29bdfd0abb5208d7830616","unresolved":false,"context_lines":[{"line_number":11,"context_line":"First you should generate or write the reference information including:"},{"line_number":12,"context_line":""},{"line_number":13,"context_line":"- Method (GET/PUT/POST/PATCH/HEAD/DELETE)"},{"line_number":14,"context_line":"- Resource (URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"}],"source_content_type":"text/x-rst","patch_set":3,"id":"fa1b9901_b1cf1d55","line":14,"updated":"2015-08-26 13:13:24.000000000","message":"Technically the resource and the URL are not the same thing, but I guess it\u0027s acceptable - at the end of the day the URL points to the resource, so I guess doing:\n\n- Resource (Identified by the URL)\n\nchanges very little","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":11,"context_line":"First you should generate or write the reference information including:"},{"line_number":12,"context_line":""},{"line_number":13,"context_line":"- Method (GET/PUT/POST/PATCH/HEAD/DELETE)"},{"line_number":14,"context_line":"- Resource (URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_c8fd2db2","line":14,"in_reply_to":"fa1b9901_b1cf1d55","updated":"2015-09-17 19:06:53.000000000","message":"I agree with the suggestion to say the resource is identified by the path","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_e8235154","line":17,"updated":"2015-09-17 19:06:53.000000000","message":"I assume this is Request Headers and not response headers, so suggest call this \"Request Headers\"","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"83db8c4846b547746e8d4f6067b8d5e0d2e60528","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a1a9d01_5973f64d","line":17,"in_reply_to":"ba15a1d1_e8235154","updated":"2015-09-24 17:09:06.000000000","message":"Object Storage API does have response header of \"Content-Type\" for an object for example, so I will separate those out. Object Storage documents nearly 70 headers in both requests and responses.","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"},{"line_number":21,"context_line":"- Status codes: successful request and error responses"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_a819d923","line":18,"updated":"2015-09-17 19:06:53.000000000","message":"what\u0027s a response parameter?","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"},{"line_number":21,"context_line":"- Status codes: successful request and error responses"},{"line_number":22,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_e8ea71da","line":19,"updated":"2015-09-17 19:06:53.000000000","message":"and headers","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":17,"context_line":"- Headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"},{"line_number":21,"context_line":"- Status codes: successful request and error responses"},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"For this reference information, use the Swagger 2.0 specification. See"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_28dce944","line":20,"updated":"2015-09-17 19:06:53.000000000","message":"and headers","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"2b60f194c82cea41984352b8e10351febf8c5499","unresolved":false,"context_lines":[{"line_number":18,"context_line":"- Responses including parameter, type and description"},{"line_number":19,"context_line":"- Example request body"},{"line_number":20,"context_line":"- Example response body"},{"line_number":21,"context_line":"- Status codes: successful request and error responses"},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"For this reference information, use the Swagger 2.0 specification. See"},{"line_number":24,"context_line":"authoring tools below for more information on writing or generating the Swagger"}],"source_content_type":"text/x-rst","patch_set":3,"id":"da20952f_d669da26","line":21,"updated":"2015-08-27 18:17:30.000000000","message":"I\u0027d like to see this list include Resource Model as well. Having the model explicitly specified is a HUGE benefit for developers. No more looking at requests and responses and their examples and trying to extrapolate the underlying model.\n\nResource Model a resource model to hold data types that can be consumed and produced by operations.\n\nThe Swagger specification of this is the Definitions Object [1]. An example of definitions is here [2] and you can see how they\u0027re referenced in the responses [3].\n\nIt\u0027s worthwhile noting that the Definitions Object really just punts to JSON Schema [4] for the actual modeling. That means we should be able to get a lot of tool reuse out of it.\n\n[1] https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#definitionsObject\n\n[2] https://github.com/swagger-api/swagger-spec/blob/master/examples/v2.0/yaml/uber.yaml#L170\n\n[3] https://github.com/swagger-api/swagger-spec/blob/master/examples/v2.0/yaml/uber.yaml#L43\n\n[4] https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":20,"context_line":"- Example response body"},{"line_number":21,"context_line":"- Status codes: successful request and error responses"},{"line_number":22,"context_line":""},{"line_number":23,"context_line":"For this reference information, use the Swagger 2.0 specification. See"},{"line_number":24,"context_line":"authoring tools below for more information on writing or generating the Swagger"},{"line_number":25,"context_line":"document."},{"line_number":26,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_68a421b9","line":23,"updated":"2015-09-17 19:06:53.000000000","message":"suggest make \"Swagger 2.0\" a link to the spec.","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":33,"context_line":"Documentation should provide a discussion about the consistency model the"},{"line_number":34,"context_line":"service provides and synchronous or asynchronous behavior for certain methods."},{"line_number":35,"context_line":""},{"line_number":36,"context_line":"As guidance, here is a list of topics to ensure you write in your API docs"},{"line_number":37,"context_line":"beyond the Swagger reference information."},{"line_number":38,"context_line":""},{"line_number":39,"context_line":" * Authentication"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_888e552c","line":36,"updated":"2015-09-17 19:06:53.000000000","message":"suggest change \"write\" to \"include\"","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":6486,"name":"Brant Knudson","email":"blk@acm.org","username":"blk-u"},"change_message_id":"74339f18c34ffb974e680f1ced7c06f0b4dce069","unresolved":false,"context_lines":[{"line_number":49,"context_line":" * Formats (request, response)"},{"line_number":50,"context_line":" * Endpoints, versions and discoverability"},{"line_number":51,"context_line":" * Capabilities and discoverability"},{"line_number":52,"context_line":" * Term definitions (links to the OpenStack glossary is best)"},{"line_number":53,"context_line":" * Status or state values"},{"line_number":54,"context_line":" * Hierarchy information"},{"line_number":55,"context_line":" * Quotas"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba15a1d1_e8a6f1ac","line":52,"updated":"2015-09-17 19:06:53.000000000","message":"suggest remove \"is best\", why not have a common glossary?","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"83db8c4846b547746e8d4f6067b8d5e0d2e60528","unresolved":false,"context_lines":[{"line_number":49,"context_line":" * Formats (request, response)"},{"line_number":50,"context_line":" * Endpoints, versions and discoverability"},{"line_number":51,"context_line":" * Capabilities and discoverability"},{"line_number":52,"context_line":" * Term definitions (links to the OpenStack glossary is best)"},{"line_number":53,"context_line":" * Status or state values"},{"line_number":54,"context_line":" * Hierarchy information"},{"line_number":55,"context_line":" * Quotas"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a1a9d01_793fda25","line":52,"in_reply_to":"ba15a1d1_e8a6f1ac","updated":"2015-09-24 17:09:06.000000000","message":"The OpenStack glossary is the common glossary we use for end-user documentation. It\u0027s sourced in the openstack-manuals repository.","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"2b60f194c82cea41984352b8e10351febf8c5499","unresolved":false,"context_lines":[{"line_number":62,"context_line":"Authoring tools"},{"line_number":63,"context_line":"---------------"},{"line_number":64,"context_line":""},{"line_number":65,"context_line":"What is Swagger? It is a community-maintained standard for REST API design and"},{"line_number":66,"context_line":"documentation with open-source tooling. Swagger can be written in a YAML format"},{"line_number":67,"context_line":"and then downloaded as a converted JSON file. It allows for inclusion of"},{"line_number":68,"context_line":"content similar to our current entities. To output the information you must run"}],"source_content_type":"text/x-rst","patch_set":3,"id":"da20952f_964a82ab","line":65,"updated":"2015-08-27 18:17:30.000000000","message":"Link to http://swagger.io/community/ here?","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"6ae68388d2086267af6920b4e4fec097cb55f768","unresolved":false,"context_lines":[{"line_number":78,"context_line":"Publishing tools"},{"line_number":79,"context_line":"----------------"},{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Within the repo at https://github.com/russell/fairy-slipper running the Pecan"},{"line_number":82,"context_line":"web app can serve RST and Swagger documentation but that tooling is not yet"},{"line_number":83,"context_line":"released, planned for the Liberty release in October 2015."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"da20952f_8acb001e","line":81,"updated":"2015-08-28 15:06:08.000000000","message":"Nit: Can you make this an actual link w/ a title?","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"83db8c4846b547746e8d4f6067b8d5e0d2e60528","unresolved":false,"context_lines":[{"line_number":78,"context_line":"Publishing tools"},{"line_number":79,"context_line":"----------------"},{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Within the repo at https://github.com/russell/fairy-slipper running the Pecan"},{"line_number":82,"context_line":"web app can serve RST and Swagger documentation but that tooling is not yet"},{"line_number":83,"context_line":"released, planned for the Liberty release in October 2015."},{"line_number":84,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a1a9d01_f9bbea73","line":81,"in_reply_to":"da20952f_8acb001e","updated":"2015-09-24 17:09:06.000000000","message":"Done","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"3fd3cba42ef73dd020d6de03470f938b2871aa97","unresolved":false,"context_lines":[{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Within the repo at https://github.com/russell/fairy-slipper running the Pecan"},{"line_number":82,"context_line":"web app can serve RST and Swagger documentation but that tooling is not yet"},{"line_number":83,"context_line":"released, planned for the Liberty release in October 2015."},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"The existing OpenStack infrastructure provides publishing to docs.openstack.org"},{"line_number":86,"context_line":"and developer.openstack.org and specs.openstack.org from RST/Sphinx. Running"}],"source_content_type":"text/x-rst","patch_set":3,"id":"fa1b9901_51eec1ed","line":83,"updated":"2015-08-26 13:09:53.000000000","message":"So perhaps we should add this paragraph in october? \n\nJust kidding it is ok as it is.","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"83db8c4846b547746e8d4f6067b8d5e0d2e60528","unresolved":false,"context_lines":[{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Within the repo at https://github.com/russell/fairy-slipper running the Pecan"},{"line_number":82,"context_line":"web app can serve RST and Swagger documentation but that tooling is not yet"},{"line_number":83,"context_line":"released, planned for the Liberty release in October 2015."},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"The existing OpenStack infrastructure provides publishing to docs.openstack.org"},{"line_number":86,"context_line":"and developer.openstack.org and specs.openstack.org from RST/Sphinx. Running"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a1a9d01_19c1fee4","line":83,"in_reply_to":"da20952f_d65a3a50","updated":"2015-09-24 17:09:06.000000000","message":"Done","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"2b60f194c82cea41984352b8e10351febf8c5499","unresolved":false,"context_lines":[{"line_number":80,"context_line":""},{"line_number":81,"context_line":"Within the repo at https://github.com/russell/fairy-slipper running the Pecan"},{"line_number":82,"context_line":"web app can serve RST and Swagger documentation but that tooling is not yet"},{"line_number":83,"context_line":"released, planned for the Liberty release in October 2015."},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"The existing OpenStack infrastructure provides publishing to docs.openstack.org"},{"line_number":86,"context_line":"and developer.openstack.org and specs.openstack.org from RST/Sphinx. Running"}],"source_content_type":"text/x-rst","patch_set":3,"id":"da20952f_d65a3a50","line":83,"in_reply_to":"fa1b9901_51eec1ed","updated":"2015-08-27 18:17:30.000000000","message":"The problem with including a speculative date like this is that you have to remember to update them. Pinky swear you\u0027ll remember?\n\nOr the paragraph could be rewritten to remove the dates.","commit_id":"f37fb5e8fbd68ea3ba65e54b71fa66eabed0db35"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"025cd71ad3141246f2f727d0f2a696f9e54ac5de","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (Identified by the URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Request headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Response headers (for some APIs)"},{"line_number":19,"context_line":"- Responses including types and description"},{"line_number":20,"context_line":"- Example request body and headers"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9a1a9d01_1ed2965c","line":17,"updated":"2015-09-29 22:38:00.000000000","message":"Should you also list query string parameters as part of the reference information?","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"10cd553664d342924962d2627d907ed091bf4e17","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (Identified by the URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Request headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Response headers (for some APIs)"},{"line_number":19,"context_line":"- Responses including types and description"},{"line_number":20,"context_line":"- Example request body and headers"}],"source_content_type":"text/x-rst","patch_set":7,"id":"7a2fa921_0302d83e","line":17,"in_reply_to":"7a2fa921_344469b5","updated":"2015-10-12 18:48:37.000000000","message":"Yeah, or perhaps change the above to: Request (query string) parameters","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"5dfec1b8853549ebb558a2b2c83533dbc22346f8","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (Identified by the URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Request headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Response headers (for some APIs)"},{"line_number":19,"context_line":"- Responses including types and description"},{"line_number":20,"context_line":"- Example request body and headers"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9a1a9d01_db189ed5","line":17,"in_reply_to":"9a1a9d01_1ed2965c","updated":"2015-09-30 10:22:36.000000000","message":"Isn\u0027t that covered by \"request parameters\" above or does it need to be more explicit?","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"86aa9b48eb266a7867de986c843de4fffd7b3ba4","unresolved":false,"context_lines":[{"line_number":14,"context_line":"- Resource (Identified by the URL)"},{"line_number":15,"context_line":"- Request parameters, type and description including whether it"},{"line_number":16,"context_line":"  is optional"},{"line_number":17,"context_line":"- Request headers including media-type, content-type, accept, and others"},{"line_number":18,"context_line":"- Response headers (for some APIs)"},{"line_number":19,"context_line":"- Responses including types and description"},{"line_number":20,"context_line":"- Example request body and headers"}],"source_content_type":"text/x-rst","patch_set":7,"id":"7a2fa921_344469b5","line":17,"in_reply_to":"9a1a9d01_db189ed5","updated":"2015-10-08 16:44:35.000000000","message":"Seems like more explanation is fine here. I can add after merging along with Atsushi\u0027s suggestion below.","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"},{"author":{"_account_id":17207,"name":"Atsushi SAKAI","email":"sakaia@jp.fujitsu.com","username":"sakaia"},"change_message_id":"c883609718b729a2aa569cc98b5093c78e378422","unresolved":false,"context_lines":[{"line_number":46,"context_line":" * Content compression"},{"line_number":47,"context_line":" * Encoding"},{"line_number":48,"context_line":" * Links and references"},{"line_number":49,"context_line":" * Pagination"},{"line_number":50,"context_line":" * Filtering"},{"line_number":51,"context_line":" * Sorting"},{"line_number":52,"context_line":" * Formats (request, response)"}],"source_content_type":"text/x-rst","patch_set":7,"id":"9a1a9d01_5d531e6b","line":49,"updated":"2015-09-30 12:58:22.000000000","message":"Some module (like Keystone v3) does not support.\nIs threre any overview of each modules policies?","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"86aa9b48eb266a7867de986c843de4fffd7b3ba4","unresolved":false,"context_lines":[{"line_number":46,"context_line":" * Content compression"},{"line_number":47,"context_line":" * Encoding"},{"line_number":48,"context_line":" * Links and references"},{"line_number":49,"context_line":" * Pagination"},{"line_number":50,"context_line":" * Filtering"},{"line_number":51,"context_line":" * Sorting"},{"line_number":52,"context_line":" * Formats (request, response)"}],"source_content_type":"text/x-rst","patch_set":7,"id":"7a2fa921_74f7418b","line":49,"in_reply_to":"9a1a9d01_5d531e6b","updated":"2015-10-08 16:44:35.000000000","message":"Oh, good question. I could: \nrevise the intro para to say \"here is a list of suggested topics to include in your API docs as applicable beyond the Swagger reference information.\" \n\nWhat do you think, would that help clarify?","commit_id":"d0d50877dc44a8da49f55623be295e76543e3b02"}]}