)]}'
{"specs/liberty/api-site.rst":[{"author":{"_account_id":6547,"name":"Andreas Jaeger","email":"jaegerandi@gmail.com","username":"jaegerandi"},"change_message_id":"8124c13c637fdaebbb5da606ae2b277d75d1d440","unresolved":false,"context_lines":[{"line_number":61,"context_line":"support of a central doc team for API docs, or strictly enforce where API"},{"line_number":62,"context_line":"reference information is maintained and built from."},{"line_number":63,"context_line":""},{"line_number":64,"context_line":"Already documented in api-site:"},{"line_number":65,"context_line":"ceilometer: Telemetry or Telemetry module"},{"line_number":66,"context_line":"cinder: OpenStack Block Storage (two versions)"},{"line_number":67,"context_line":"glance: OpenStack Image service (two versions)"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5ad0253b_92106d50","line":64,"updated":"2015-04-28 20:06:06.000000000","message":"Use an itemized list, this will not render nicely otherwise.","commit_id":"2ad0700b2e6671bed5ee03b5597394c7607d70c1"},{"author":{"_account_id":6547,"name":"Andreas Jaeger","email":"jaegerandi@gmail.com","username":"jaegerandi"},"change_message_id":"8124c13c637fdaebbb5da606ae2b277d75d1d440","unresolved":false,"context_lines":[{"line_number":74,"context_line":"trove: Database service for OpenStack"},{"line_number":75,"context_line":""},{"line_number":76,"context_line":"API docs elsewhere or unknown state:"},{"line_number":77,"context_line":"barbican: Key management service"},{"line_number":78,"context_line":"ironic: Bare metal service"},{"line_number":79,"context_line":"tripleo: Deployment"},{"line_number":80,"context_line":"zaqar: Message service"}],"source_content_type":"text/x-rst","patch_set":1,"id":"5ad0253b_f21fa159","line":77,"updated":"2015-04-28 20:06:06.000000000","message":"itemezid list or definition list","commit_id":"2ad0700b2e6671bed5ee03b5597394c7607d70c1"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"abf5289dab739cb8132cdad1548a83b65e2a951a","unresolved":false,"context_lines":[{"line_number":67,"context_line":"infrastructure services used most based on the most recent User Guide survey."},{"line_number":68,"context_line":""},{"line_number":69,"context_line":"* Identity v2.0"},{"line_number":70,"context_line":"* Compute v2"},{"line_number":71,"context_line":"* Block Storage v2"},{"line_number":72,"context_line":"* Image service v2"},{"line_number":73,"context_line":"* Networking v2.0"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_9a5d9d17","line":70,"updated":"2015-06-09 08:13:28.000000000","message":"Nova in the scope, so that means we needn\u0027t fix the problem in api ref based on WADL in api-sites anymore for now?","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":1991,"name":"Russell Sim","email":"russell.sim@gmail.com","username":"russell-sim"},"change_message_id":"d837ecb83ec597a6ea17051b30e274b4402cb73c","unresolved":false,"context_lines":[{"line_number":67,"context_line":"infrastructure services used most based on the most recent User Guide survey."},{"line_number":68,"context_line":""},{"line_number":69,"context_line":"* Identity v2.0"},{"line_number":70,"context_line":"* Compute v2"},{"line_number":71,"context_line":"* Block Storage v2"},{"line_number":72,"context_line":"* Image service v2"},{"line_number":73,"context_line":"* Networking v2.0"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_48807ff7","line":70,"in_reply_to":"3afb71cf_9a5d9d17","updated":"2015-06-09 09:03:41.000000000","message":"We are going to use the WADL as the basis for any documentation that is embedded in the code.  It would be best if it\u0027s state continued to improve.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":1991,"name":"Russell Sim","email":"russell.sim@gmail.com","username":"russell-sim"},"change_message_id":"d837ecb83ec597a6ea17051b30e274b4402cb73c","unresolved":false,"context_lines":[{"line_number":101,"context_line":"  - Neutron: routes"},{"line_number":102,"context_line":"  - Heat: routes"},{"line_number":103,"context_line":"  - Saraha: flask"},{"line_number":104,"context_line":"  - Swift: None"},{"line_number":105,"context_line":""},{"line_number":106,"context_line":"For reference, these projects are already documented in the openstack/api-site"},{"line_number":107,"context_line":"repository:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_48ae3f82","line":104,"updated":"2015-06-09 09:03:41.000000000","message":"Keystone also uses routes.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":612,"name":"Tom Fifield","email":"tom@openstack.org","username":"fifieldt"},"change_message_id":"52e4c3f604af7020721b42f7d07affe3f158a417","unresolved":false,"context_lines":[{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Contract validation: Optionally, must provide validation of requests and"},{"line_number":168,"context_line":"responses as valid and would work against a public cloud endpoint."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":".. _overview-of-standards:"},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"Overview of standards"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_9d94ace2","line":169,"updated":"2015-06-08 08:23:30.000000000","message":"+ potential optional feature: Review assistance: Since documentation reviewers might not catch every change that goes in (eg due to there being too many patches, or patches not tagged with APIImpact), we could generate a view of changes aimed at documentation reviewers. Call it \"changes this week\" or similar. This could be used as a back-stop and relatively quickly scanned looking for eg language that could be fixed, inconsistencies in examples, parameter naming, potential for better human grouping and so on.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"d73bb70905d5c2d8c9544f80fd678fa8efa30a81","unresolved":false,"context_lines":[{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Contract validation: Optionally, must provide validation of requests and"},{"line_number":168,"context_line":"responses as valid and would work against a public cloud endpoint."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":".. _overview-of-standards:"},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"Overview of standards"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_adc83e23","line":169,"in_reply_to":"3afb71cf_9d94ace2","updated":"2015-06-08 18:41:09.000000000","message":"That would be a great feature.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"98574c8bc8881733de33270c16dccbfdf10f607f","unresolved":false,"context_lines":[{"line_number":166,"context_line":""},{"line_number":167,"context_line":"Contract validation: Optionally, must provide validation of requests and"},{"line_number":168,"context_line":"responses as valid and would work against a public cloud endpoint."},{"line_number":169,"context_line":""},{"line_number":170,"context_line":".. _overview-of-standards:"},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"Overview of standards"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_1083f099","line":169,"in_reply_to":"3afb71cf_9d94ace2","updated":"2015-06-08 15:26:11.000000000","message":"nice idea, +1","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":1991,"name":"Russell Sim","email":"russell.sim@gmail.com","username":"russell-sim"},"change_message_id":"1100a8f1eaee26fe401447e14a54e7859686d52d","unresolved":false,"context_lines":[{"line_number":212,"context_line":"Considerations"},{"line_number":213,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":214,"context_line":""},{"line_number":215,"context_line":"Russel Sims has done a proof of concept for Volume API v2. He can upload an"},{"line_number":216,"context_line":"example for the rest of the team to start working on. He investigated using"},{"line_number":217,"context_line":"httpdomain, but it seems that it would require depending on sphinx in"},{"line_number":218,"context_line":"production, angering packagers and operators alike. Instead he is making"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_2bcb4455","line":215,"updated":"2015-06-07 00:46:21.000000000","message":"Russell Sim","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"d73bb70905d5c2d8c9544f80fd678fa8efa30a81","unresolved":false,"context_lines":[{"line_number":212,"context_line":"Considerations"},{"line_number":213,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":214,"context_line":""},{"line_number":215,"context_line":"Russel Sims has done a proof of concept for Volume API v2. He can upload an"},{"line_number":216,"context_line":"example for the rest of the team to start working on. He investigated using"},{"line_number":217,"context_line":"httpdomain, but it seems that it would require depending on sphinx in"},{"line_number":218,"context_line":"production, angering packagers and operators alike. Instead he is making"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_4dd54ab7","line":215,"in_reply_to":"3afb71cf_2bcb4455","updated":"2015-06-08 18:41:09.000000000","message":"Sorry Russell! Took away an L and gave you an S I did.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"e472edba15e9d2549a5bd536a62cce9d126bd1d8","unresolved":false,"context_lines":[{"line_number":232,"context_line":""},{"line_number":233,"context_line":"Could keep what we currently have in api-site and WADL. However this requires"},{"line_number":234,"context_line":"the continued use of clouddocs-maven-plugin for builds, which currently has no"},{"line_number":235,"context_line":"maintainers."},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"Implementation"},{"line_number":238,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_d8dc72e6","line":235,"updated":"2015-06-08 08:50:18.000000000","message":"While this is clearly a great step forward, it doesn\u0027t seem like swagger has support for the microversion system?\n\nA reasonable example for API docs where you have \"new in version\" and \"changed in version\" and \"deprecated since\", is probably here:\nhttps://docs.python.org/2/library/unittest.html#unittest.TestCase.assertNotAlmostEqual\n\nI get the impression swagger does the deprecated bit, just I am not sure about the others.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":1991,"name":"Russell Sim","email":"russell.sim@gmail.com","username":"russell-sim"},"change_message_id":"d837ecb83ec597a6ea17051b30e274b4402cb73c","unresolved":false,"context_lines":[{"line_number":232,"context_line":""},{"line_number":233,"context_line":"Could keep what we currently have in api-site and WADL. However this requires"},{"line_number":234,"context_line":"the continued use of clouddocs-maven-plugin for builds, which currently has no"},{"line_number":235,"context_line":"maintainers."},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"Implementation"},{"line_number":238,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_68da1b4e","line":235,"in_reply_to":"3afb71cf_0d5bd255","updated":"2015-06-09 09:03:41.000000000","message":"We do have the option to extend swagger to add in the version number to each of the request/response parameters and the request/response objects. But this will require more client side complexity in the JS to create a view of the actual request at any particular version.\n\nAlso it\u0027s important to note that there may be an explosion of documentation as we would need one docstring that documents each new call for each microversion.  There isn\u0027t really any scope for reuse because anything could be changed in each version.  We could look at extending the httpdomain syntax to support some version syntax so that we can reuse some parts of the documentation but until we see micro-versions in the wild, i don\u0027t want to assume how they will be used.\n\nThis will also mean an explosion of examples..  but we may be able to autogenerate examples.\n\nIn regards to microversions. Nothing supports them. not WADL. not Swagger.   The reason for using something like swagger is that it\u0027s well defined and easy to generate.  We may have to extend it, we may be able to just use it as is with one API description per-microversion,  whatever works.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"d73bb70905d5c2d8c9544f80fd678fa8efa30a81","unresolved":false,"context_lines":[{"line_number":232,"context_line":""},{"line_number":233,"context_line":"Could keep what we currently have in api-site and WADL. However this requires"},{"line_number":234,"context_line":"the continued use of clouddocs-maven-plugin for builds, which currently has no"},{"line_number":235,"context_line":"maintainers."},{"line_number":236,"context_line":""},{"line_number":237,"context_line":"Implementation"},{"line_number":238,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_0d5bd255","line":235,"in_reply_to":"3afb71cf_d8dc72e6","updated":"2015-06-08 18:41:09.000000000","message":"We discussed at the summit, that we\u0027ll have to do a research spike for microversions, but our thinking is: \n1. Swagger file per microversion\n2. Display of different versions with a drop-down like this page: https://libgit2.github.com/libgit2/#HEAD","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":612,"name":"Tom Fifield","email":"tom@openstack.org","username":"fifieldt"},"change_message_id":"52e4c3f604af7020721b42f7d07affe3f158a417","unresolved":false,"context_lines":[{"line_number":282,"context_line":""},{"line_number":283,"context_line":"* https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference"},{"line_number":284,"context_line":"  I don\u0027t believe we want to autogenerate if we want these docs to serve"},{"line_number":285,"context_line":"  as a contract for testing purposes."},{"line_number":286,"context_line":"* https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site"},{"line_number":287,"context_line":"  Moving content to project repos would be the opposite moving direction"},{"line_number":288,"context_line":"  and may work perfectly well for this use case."}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_1db79c87","line":285,"updated":"2015-06-08 08:23:30.000000000","message":"not sure if this sentence should be changing after recent discussions?","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"d73bb70905d5c2d8c9544f80fd678fa8efa30a81","unresolved":false,"context_lines":[{"line_number":282,"context_line":""},{"line_number":283,"context_line":"* https://blueprints.launchpad.net/openstack-manuals/+spec/autogenerate-api-reference"},{"line_number":284,"context_line":"  I don\u0027t believe we want to autogenerate if we want these docs to serve"},{"line_number":285,"context_line":"  as a contract for testing purposes."},{"line_number":286,"context_line":"* https://blueprints.launchpad.net/openstack-manuals/+spec/api-samples-to-api-site"},{"line_number":287,"context_line":"  Moving content to project repos would be the opposite moving direction"},{"line_number":288,"context_line":"  and may work perfectly well for this use case."}],"source_content_type":"text/x-rst","patch_set":5,"id":"3afb71cf_cd549a22","line":285,"in_reply_to":"3afb71cf_1db79c87","updated":"2015-06-08 18:41:09.000000000","message":"Yep, will do.","commit_id":"81ac5f05a8bcd595f3335011df3ee6fea84d4eb5"},{"author":{"_account_id":1991,"name":"Russell Sim","email":"russell.sim@gmail.com","username":"russell-sim"},"change_message_id":"e9d643c1500117abd311bd0dbfed5cc785e5cd10","unresolved":false,"context_lines":[{"line_number":199,"context_line":"   Community-maintained standard, proprietary tooling unless you just edit"},{"line_number":200,"context_line":"   in text, but then how do you validate? Allows for inclusion of content"},{"line_number":201,"context_line":"   similar to our current entities."},{"line_number":202,"context_line":""},{"line_number":203,"context_line":"WADL"},{"line_number":204,"context_line":"   Currently all the reference information is housed and maintained in"},{"line_number":205,"context_line":"   openstack/api-site in WADL files. We have a `WADL2Swagger tool \u003chttps://github.com/rackerlabs/wadl2swagger\u003e`_"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3afb71cf_a787bdb3","line":202,"updated":"2015-06-11 02:01:43.000000000","message":"Can you please add another standard here.\n\nThe other standard is API-Blueprint  https://github.com/apiaryio/api-blueprint/\n\nIt\u0027s supported by a company called https://apiary.io/ who provide interfaces and generated document hosting.  Apiary seems to be the main driver, but they are accepting patches from the community.  The spec is here https://github.com/apiaryio/api-blueprint-ast\n\nIt has tooling to convert a markdown format to a JSON format.  I imagine that we will just output JSON from our RST definitions in their format.\n\nFrom what i can see it doesn\u0027t support JSON schema to define request/response payloads explicitly in the documentation, but they don\u0027t really define what it can be so i would think that adding the schema in there should be fine. https://github.com/apiaryio/api-blueprint-ast#asset-element\n\nIt also appears that this format doesn\u0027t support a data structure that will allow us to have multiple request/response combinations for the same endpoint.  Sadly.  I believed it might be a solution until I went to write this paragraph :(","commit_id":"d69aa56f32147fade0bb4de7cfef023a4e381935"},{"author":{"_account_id":964,"name":"Anne Gentle","email":"annegentle@justwriteclick.com","username":"annegentle"},"change_message_id":"33963b1c841b0e3eb4a01e5e47f9b8e72c51ae77","unresolved":false,"context_lines":[{"line_number":199,"context_line":"   Community-maintained standard, proprietary tooling unless you just edit"},{"line_number":200,"context_line":"   in text, but then how do you validate? Allows for inclusion of content"},{"line_number":201,"context_line":"   similar to our current entities."},{"line_number":202,"context_line":""},{"line_number":203,"context_line":"WADL"},{"line_number":204,"context_line":"   Currently all the reference information is housed and maintained in"},{"line_number":205,"context_line":"   openstack/api-site in WADL files. We have a `WADL2Swagger tool \u003chttps://github.com/rackerlabs/wadl2swagger\u003e`_"}],"source_content_type":"text/x-rst","patch_set":6,"id":"1af86dd1_6d5f320f","line":202,"in_reply_to":"3afb71cf_a787bdb3","updated":"2015-06-30 18:31:47.000000000","message":"Oh yes, good point. I added it, but also wanted to comment that we did some research in converting and have some WADL to api-blueprint converted files but found it too simple for our needs.","commit_id":"d69aa56f32147fade0bb4de7cfef023a4e381935"}]}