)]}'
{"doc/source/contributor/api-ref-guideline.rst":[{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"ec3a5dd1e4674ec33652bf86d8e4bbdf73d329ca","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"Example"},{"line_number":214,"context_line":"-------"},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"All request and response have valid sample files."},{"line_number":217,"context_line":"These come from the ``/doc/api_samples/`` directory."},{"line_number":218,"context_line":"The examples must have an explanation of what it is attempting to do"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_508378a9","line":215,"updated":"2018-09-20 15:53:10.000000000","message":"I\u0027m a little confused. Is the intent of this section to describe what we should put in the `Example` section for an API operation?\n\nIt starts by implying that there should always be sample files. But that\u0027s not true for operations with no payload in the request and/or response - which you imply later by allowing for L224.\n\nHere\u0027s a stab at a reword:\n\nOne or more examples should be provided for operations whose request and/or response contains a payload. The example should describe what the operation is attempting to do and provide a sample payload for the request and/or response as appropriate. Sample files should be created in the ``doc/api_samples`` directory and inlined by inclusion. When an operation has no payload, a suitable message should be included. For example::\n\n  There is no body content for the response of a successful DELETE query.\n\nExamples for multiple microversions should be included in ascending microversion order.","commit_id":"75bd5f5e7594131e0a11f43dfa6fbc417d87fb9f"},{"author":{"_account_id":7634,"name":"Takashi Natsume","email":"takanattie@gmail.com","username":"natsumet"},"change_message_id":"b5c51df21aca434098187dfde207f50d93fda180","unresolved":false,"context_lines":[{"line_number":212,"context_line":""},{"line_number":213,"context_line":"Example"},{"line_number":214,"context_line":"-------"},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"All request and response have valid sample files."},{"line_number":217,"context_line":"These come from the ``/doc/api_samples/`` directory."},{"line_number":218,"context_line":"The examples must have an explanation of what it is attempting to do"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_61e57da3","line":215,"in_reply_to":"3f79a3b5_508378a9","updated":"2018-09-21 07:53:31.000000000","message":"Thank you. Done.","commit_id":"75bd5f5e7594131e0a11f43dfa6fbc417d87fb9f"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"ec3a5dd1e4674ec33652bf86d8e4bbdf73d329ca","unresolved":false,"context_lines":[{"line_number":214,"context_line":"-------"},{"line_number":215,"context_line":""},{"line_number":216,"context_line":"All request and response have valid sample files."},{"line_number":217,"context_line":"These come from the ``/doc/api_samples/`` directory."},{"line_number":218,"context_line":"The examples must have an explanation of what it is attempting to do"},{"line_number":219,"context_line":"or an expression of what was done and then the request returned."},{"line_number":220,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_d02d48fd","line":217,"range":{"start_line":217,"start_character":22,"end_line":217,"end_character":23},"updated":"2018-09-20 15:53:10.000000000","message":"strike leading slash","commit_id":"75bd5f5e7594131e0a11f43dfa6fbc417d87fb9f"},{"author":{"_account_id":14070,"name":"Eric Fried","email":"openstack@fried.cc","username":"efried"},"change_message_id":"ec3a5dd1e4674ec33652bf86d8e4bbdf73d329ca","unresolved":false,"context_lines":[{"line_number":216,"context_line":"All request and response have valid sample files."},{"line_number":217,"context_line":"These come from the ``/doc/api_samples/`` directory."},{"line_number":218,"context_line":"The examples must have an explanation of what it is attempting to do"},{"line_number":219,"context_line":"or an expression of what was done and then the request returned."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":"When a response has no JSON context and relies on the HTTP response code"},{"line_number":222,"context_line":"(e.g. such as a DELETE), a suitable message should be included. For example::"}],"source_content_type":"text/x-rst","patch_set":1,"id":"3f79a3b5_533b82c6","line":219,"range":{"start_line":219,"start_character":47,"end_line":219,"end_character":54},"updated":"2018-09-20 15:53:10.000000000","message":"response","commit_id":"75bd5f5e7594131e0a11f43dfa6fbc417d87fb9f"},{"author":{"_account_id":8556,"name":"Ghanshyam Maan","display_name":"Ghanshyam Maan","email":"gmaan.os14@gmail.com","username":"ghanshyam"},"change_message_id":"eff866693d93cf9ebe1c3bd9b69002755526918b","unresolved":false,"context_lines":[{"line_number":217,"context_line":"response contains a payload. The example should describe what the operation"},{"line_number":218,"context_line":"is attempting to do and provide a sample payload for the request and/or"},{"line_number":219,"context_line":"response as appropriate."},{"line_number":220,"context_line":"Sample files should be created in the ``doc/api_samples`` directory and inlined"},{"line_number":221,"context_line":"by inclusion."},{"line_number":222,"context_line":""},{"line_number":223,"context_line":"When an operation has no payload in the response, a suitable message should be"},{"line_number":224,"context_line":"included. For example::"}],"source_content_type":"text/x-rst","patch_set":4,"id":"3f79a3b5_5b6d9b2d","line":221,"range":{"start_line":220,"start_character":0,"end_line":221,"end_character":13},"updated":"2018-10-18 10:21:33.000000000","message":"these files are auto generated from sample tests. we should tell here how we should generate those.\n- Add Sample functional tests under ``nova/tests/functional/api_sample_tests``\n- Generate the doc sample files by running tox ``api-samples`` env.","commit_id":"647b77220535e2fe2034bdbfab7bd8a03b1ee652"}]}