)]}'
{"guidelines/api-schema.rst":[{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"334152bdbd3e8f20222592c6fcdb5d479689b4ea","unresolved":false,"context_lines":[{"line_number":2,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":3,"context_line":""},{"line_number":4,"context_line":"Provide guidance for consuming OpenStack APIs schema."},{"line_number":5,"context_line":"The API schema provided by each OpenStack project (wth a REST service) can be interacted with to offer more automation."},{"line_number":6,"context_line":"This guide provides help to interact with the APIs through their schema definitions."},{"line_number":7,"context_line":""},{"line_number":8,"context_line":"There are no formal API schema definition yet, meanwhile OpenStack APIs are quite consistent by following a common"}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_17c80320","line":5,"updated":"2017-12-06 11:10:39.000000000","message":"typo: with\n\nAlso it\u0027s unclear what you mean by \"provided by each project\". is it your desired state? because it\u0027s pretty clear that not all projects provide schemas.","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"49e80847509089bb39bfe179bd018e02cee1c3ea","unresolved":false,"context_lines":[{"line_number":2,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":3,"context_line":""},{"line_number":4,"context_line":"Provide guidance for consuming OpenStack APIs schema."},{"line_number":5,"context_line":"The API schema provided by each OpenStack project (wth a REST service) can be interacted with to offer more automation."},{"line_number":6,"context_line":"This guide provides help to interact with the APIs through their schema definitions."},{"line_number":7,"context_line":""},{"line_number":8,"context_line":"There are no formal API schema definition yet, meanwhile OpenStack APIs are quite consistent by following a common"}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_f280dbc1","line":5,"in_reply_to":"df87a7cf_17c80320","updated":"2017-12-07 23:33:51.000000000","message":"Yes that\u0027s what I mean, let me rephrase","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"334152bdbd3e8f20222592c6fcdb5d479689b4ea","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Current situation"},{"line_number":13,"context_line":"-----------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"APIs schema are available through the API documentation (http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html)"},{"line_number":16,"context_line":"through the RST/Sphinx used by the publishing tools."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"Each project\u0027s API schema is defined in its project source repository."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_37cbc71e","line":15,"updated":"2017-12-06 11:10:39.000000000","message":"I cannot find a single mention of the word \"schema\" in this document. Do you mean a human-readable explanation? If so, it\u0027s not trivial to use from tools","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"49e80847509089bb39bfe179bd018e02cee1c3ea","unresolved":false,"context_lines":[{"line_number":12,"context_line":"Current situation"},{"line_number":13,"context_line":"-----------------"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"APIs schema are available through the API documentation (http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html)"},{"line_number":16,"context_line":"through the RST/Sphinx used by the publishing tools."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"Each project\u0027s API schema is defined in its project source repository."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_d2d917f3","line":15,"in_reply_to":"df87a7cf_37cbc71e","updated":"2017-12-07 23:33:51.000000000","message":"That\u0027s right there is not mention of API schema but the OpenAPI/swagger is mentioned. Which is not obvious is the fact that the API schema tree is used for the documentation.","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"334152bdbd3e8f20222592c6fcdb5d479689b4ea","unresolved":false,"context_lines":[{"line_number":16,"context_line":"through the RST/Sphinx used by the publishing tools."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"Each project\u0027s API schema is defined in its project source repository."},{"line_number":19,"context_line":"For example: https://github.com/openstack/nova/blob/master/api-ref/source/flavors.inc"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Ojective"}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_d7d13bcf","line":19,"updated":"2017-12-06 11:10:39.000000000","message":"Oh, I\u0027m starting to get what you mean :) Let\u0027s begin this document with the definition of \"schema\" within it. I was imagining something like a JSON schema.\n\nAnd my previous point holds valid: I\u0027m not sure every project publishes an api-ref. ironic-inspector does not for sure. We may be able to talk about \"the majority\", I guess.","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"49e80847509089bb39bfe179bd018e02cee1c3ea","unresolved":false,"context_lines":[{"line_number":16,"context_line":"through the RST/Sphinx used by the publishing tools."},{"line_number":17,"context_line":""},{"line_number":18,"context_line":"Each project\u0027s API schema is defined in its project source repository."},{"line_number":19,"context_line":"For example: https://github.com/openstack/nova/blob/master/api-ref/source/flavors.inc"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Ojective"}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_b27813c4","line":19,"in_reply_to":"df87a7cf_d7d13bcf","updated":"2017-12-07 23:33:51.000000000","message":"Well I believe a formal API schema tree has to be defined in a some sort of format like JSON or YAML, the current format is RST and the definition is informal.\n\nAll projects under api-guide (ex api-ref) use the same guidelines in order to produce a consistent reference:  \n\nhttps://developer.openstack.org/api-guide/quick-start/\n\nSo yes that\u0027s the majority and the missing ones to be rallied anyway.","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"334152bdbd3e8f20222592c6fcdb5d479689b4ea","unresolved":false,"context_lines":[{"line_number":19,"context_line":"For example: https://github.com/openstack/nova/blob/master/api-ref/source/flavors.inc"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Ojective"},{"line_number":23,"context_line":"--------"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"Have the API schema generated in a format such as JSON or YAML to be able to be consumed directly by machines."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_f7d47fbf","line":22,"updated":"2017-12-06 11:10:39.000000000","message":"typo: Objective","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"49e80847509089bb39bfe179bd018e02cee1c3ea","unresolved":false,"context_lines":[{"line_number":19,"context_line":"For example: https://github.com/openstack/nova/blob/master/api-ref/source/flavors.inc"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Ojective"},{"line_number":23,"context_line":"--------"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"Have the API schema generated in a format such as JSON or YAML to be able to be consumed directly by machines."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_727e0bb0","line":22,"in_reply_to":"df87a7cf_f7d47fbf","updated":"2017-12-07 23:33:51.000000000","message":"Done","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"334152bdbd3e8f20222592c6fcdb5d479689b4ea","unresolved":false,"context_lines":[{"line_number":22,"context_line":"Ojective"},{"line_number":23,"context_line":"--------"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"Have the API schema generated in a format such as JSON or YAML to be able to be consumed directly by machines."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_97dbb3eb","line":25,"updated":"2017-12-06 11:10:39.000000000","message":"Mmmm, is it objective of this guideline? Like, are you proposing a tool to convert RST to JSON schema (for example) or is this guideline about consuming the RST \"schema\" directly?","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"49e80847509089bb39bfe179bd018e02cee1c3ea","unresolved":false,"context_lines":[{"line_number":22,"context_line":"Ojective"},{"line_number":23,"context_line":"--------"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"Have the API schema generated in a format such as JSON or YAML to be able to be consumed directly by machines."}],"source_content_type":"text/x-rst","patch_set":1,"id":"df87a7cf_3233a316","line":25,"in_reply_to":"df87a7cf_97dbb3eb","updated":"2017-12-07 23:33:51.000000000","message":"Actually sphinx is to generate the schema since it\u0027s already in memory, that would be less disruptive from the current process.\n\nSince that has been clarified at last weekly meeting I\u0027ll update the document accordingly.","commit_id":"833009acc9565d3eb1b8ff53927553b93c297a5b"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"1cf9b0af431976cd4bd2cddd7a0bc80f01decde0","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs developments because API schemas definitions"},{"line_number":20,"context_line":"are language independent. It also allows SDKs to be closer to OpenStack projects life cycles by offering more"},{"line_number":21,"context_line":"exhaustive and up to date features. Currently all SDKs are struggling to keep up, mostly because part-time/lack of"},{"line_number":22,"context_line":"resources but ultimately because we\u0027re facing information entropy which requires simplification with more automation."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such as OpenAPI(Swagger), provided there is"},{"line_number":25,"context_line":"support for microversions, althought that would have to be discussed and agreed across the OpenStack community."}],"source_content_type":"text/x-rst","patch_set":2,"id":"df87a7cf_47a09042","line":22,"range":{"start_line":21,"start_character":36,"end_line":22,"end_character":117},"updated":"2017-12-12 11:23:32.000000000","message":"you might consider emphasizing this point a bit more by moving a version of it into the intro. The document needs to explain, early on, why we need the automation you\u0027re suggesting, and this is the compelling point.","commit_id":"15d82c374eb6a3b48cbdb80163df446e8a9aa3d9"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"041d428850c2643c320532c92a4857cb65595d50","unresolved":false,"context_lines":[{"line_number":18,"context_line":""},{"line_number":19,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs developments because API schemas definitions"},{"line_number":20,"context_line":"are language independent. It also allows SDKs to be closer to OpenStack projects life cycles by offering more"},{"line_number":21,"context_line":"exhaustive and up to date features. Currently all SDKs are struggling to keep up, mostly because part-time/lack of"},{"line_number":22,"context_line":"resources but ultimately because we\u0027re facing information entropy which requires simplification with more automation."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such as OpenAPI(Swagger), provided there is"},{"line_number":25,"context_line":"support for microversions, althought that would have to be discussed and agreed across the OpenStack community."}],"source_content_type":"text/x-rst","patch_set":2,"id":"df87a7cf_c8608c04","line":22,"range":{"start_line":21,"start_character":36,"end_line":22,"end_character":117},"in_reply_to":"df87a7cf_47a09042","updated":"2017-12-19 02:33:52.000000000","message":"Done","commit_id":"15d82c374eb6a3b48cbdb80163df446e8a9aa3d9"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac345f6d27399dec7eb0e3373d5c89c78cd5e6b1","unresolved":false,"context_lines":[{"line_number":25,"context_line":"in order to stay up to date. Although SDKs contributors are mostly working part"},{"line_number":26,"context_line":"time and/or are lacking resources, the main reason is likely an information"},{"line_number":27,"context_line":"entropy issue exposed by the APIs. This is why adding more automation capability"},{"line_number":28,"context_line":"will help on both side of the APIs, the producers and its consumers."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_d28cfcd8","line":28,"updated":"2018-03-21 00:56:14.000000000","message":"Another merit is easy to measure API coverage on integration tests from QA viewpoint.\nFor example, Kubernetes provides OpenAPI spec data and I created the measuring tool for its integration test.\n\nhttps://github.com/kubernetes/test-infra/tree/master/experiment/coverage","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"b7a582ab46e612b0bcfb3e0c64465a7f7efe4b26","unresolved":false,"context_lines":[{"line_number":25,"context_line":"in order to stay up to date. Although SDKs contributors are mostly working part"},{"line_number":26,"context_line":"time and/or are lacking resources, the main reason is likely an information"},{"line_number":27,"context_line":"entropy issue exposed by the APIs. This is why adding more automation capability"},{"line_number":28,"context_line":"will help on both side of the APIs, the producers and its consumers."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"}],"source_content_type":"text/x-rst","patch_set":5,"id":"bf659307_d7041a7e","line":28,"in_reply_to":"df7087c5_0dd6aa28","updated":"2018-03-26 04:53:26.000000000","message":"Updated document accordingly","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"1183fd07c811f974557794a05431b726f2bdd988","unresolved":false,"context_lines":[{"line_number":25,"context_line":"in order to stay up to date. Although SDKs contributors are mostly working part"},{"line_number":26,"context_line":"time and/or are lacking resources, the main reason is likely an information"},{"line_number":27,"context_line":"entropy issue exposed by the APIs. This is why adding more automation capability"},{"line_number":28,"context_line":"will help on both side of the APIs, the producers and its consumers."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_0dd6aa28","line":28,"in_reply_to":"df7087c5_d28cfcd8","updated":"2018-03-22 09:02:48.000000000","message":"Thanks! That sound like music to me. I\u0027ll add this to document as well as updates after we brain storm the below comments a bit more.","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac345f6d27399dec7eb0e3373d5c89c78cd5e6b1","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"},{"line_number":32,"context_line":"An API schema is a tree structure describing in a formal way the resources"},{"line_number":33,"context_line":"provided by a REST service."},{"line_number":34,"context_line":"Basically this is the same as the reference documentation but available in tree"},{"line_number":35,"context_line":"form using a JSON or YAML format."},{"line_number":36,"context_line":"For more details please refer to https://swagger.io/specification/"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs"},{"line_number":39,"context_line":"developments because API schemas definitions are language independent. It also"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_922d24ff","line":36,"range":{"start_line":32,"start_character":0,"end_line":36,"end_character":66},"updated":"2018-03-21 00:56:14.000000000","message":"I am confused what is difference between this \"API schema\" and OpenAPI. If this is OpenAPI itself, please use OpenAPI instead of a new definition.\n\nMy following comment is based on OpenAPI.","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"b7a582ab46e612b0bcfb3e0c64465a7f7efe4b26","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"},{"line_number":32,"context_line":"An API schema is a tree structure describing in a formal way the resources"},{"line_number":33,"context_line":"provided by a REST service."},{"line_number":34,"context_line":"Basically this is the same as the reference documentation but available in tree"},{"line_number":35,"context_line":"form using a JSON or YAML format."},{"line_number":36,"context_line":"For more details please refer to https://swagger.io/specification/"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs"},{"line_number":39,"context_line":"developments because API schemas definitions are language independent. It also"}],"source_content_type":"text/x-rst","patch_set":5,"id":"bf659307_b7ff2666","line":36,"range":{"start_line":32,"start_character":0,"end_line":36,"end_character":66},"in_reply_to":"df7087c5_15954733","updated":"2018-03-26 04:53:26.000000000","message":"I have updated the document, where I refer to outside link about API DL comparisons. I\u0027m not sure this document is where such vote should take place (but why not if there is no other choice).","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"beefce2d38163485e435aea39ecbc60aa597349e","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"},{"line_number":32,"context_line":"An API schema is a tree structure describing in a formal way the resources"},{"line_number":33,"context_line":"provided by a REST service."},{"line_number":34,"context_line":"Basically this is the same as the reference documentation but available in tree"},{"line_number":35,"context_line":"form using a JSON or YAML format."},{"line_number":36,"context_line":"For more details please refer to https://swagger.io/specification/"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs"},{"line_number":39,"context_line":"developments because API schemas definitions are language independent. It also"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_15954733","line":36,"range":{"start_line":32,"start_character":0,"end_line":36,"end_character":66},"in_reply_to":"df7087c5_2a80348b","updated":"2018-03-22 17:16:51.000000000","message":"\u003e But before even considering any API standard, we need to\n \u003e have a normalized API schema. Although there are no\n \u003e official API schema defined within the community, the\n \u003e common practice has created a \"de-facto\" API schema model\n \u003e which is informal. So we need to formalize that first.\n\nOK, how about changing this spec like\n\n Definition of API schema\n ------------------------\n ...\n\n\n Requirements of API schema\n --------------------------\n ...\n\n\n Candidates of API schema\n ------------------------\n OpenAPI (aka Swagger)\n - Pros\n   ...\n - Cons\n   ...\n JSON-Home\n - Pros\n   ...\n - Cons\n   ...\n foo\n   ...","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"1183fd07c811f974557794a05431b726f2bdd988","unresolved":false,"context_lines":[{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Definition"},{"line_number":31,"context_line":"----------"},{"line_number":32,"context_line":"An API schema is a tree structure describing in a formal way the resources"},{"line_number":33,"context_line":"provided by a REST service."},{"line_number":34,"context_line":"Basically this is the same as the reference documentation but available in tree"},{"line_number":35,"context_line":"form using a JSON or YAML format."},{"line_number":36,"context_line":"For more details please refer to https://swagger.io/specification/"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"One immediate application is to facilitate and accelerate OpenStack SDKs"},{"line_number":39,"context_line":"developments because API schemas definitions are language independent. It also"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_2a80348b","line":36,"range":{"start_line":32,"start_character":0,"end_line":36,"end_character":66},"in_reply_to":"df7087c5_922d24ff","updated":"2018-03-22 09:02:48.000000000","message":"You\u0027re touching the most \u0027sensitive\u0027 part here!\n\nAt the moment OpenStack APIs are not supporting any API standard. OpenAPI (ex swagger) was the closest candidate but the main blocker is because Microversion is not supported by OpenAPI.\n\nBut before even considering any API standard, we need to have a normalized API schema. Although there are no official API schema defined within the community, the common practice has created a \"de-facto\" API schema model which is informal. So we need to formalize that first.\n\nPart of the process here is to make sure everyone understand API schema means API standard such as OpenAPI is a good thing. And like many other things in the Open Source world we exist and rely on open standards.  \n\nAlso this represents a challenge for the API SIG, to be able to take a top-bottom approach instead of the usual opposite where various projects have been pushing things up, like the microversion. So are the projects going to agree to support API Schema normalization?","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"ac345f6d27399dec7eb0e3373d5c89c78cd5e6b1","unresolved":false,"context_lines":[{"line_number":41,"context_line":"exhaustive and up to date features."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such"},{"line_number":44,"context_line":"as OpenAPI(Swagger), provided there is support for microversions, although that"},{"line_number":45,"context_line":"would have to be discussed and agreed across the OpenStack community."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"All projects under the wings of the api-guide are already providing de-facto but"},{"line_number":48,"context_line":"informal schemas. The initial work requires to use the existing informal API"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_b2e388a4","line":45,"range":{"start_line":44,"start_character":21,"end_line":45,"end_character":69},"updated":"2018-03-21 00:56:14.000000000","message":"I think microversions itself can be solved.\nIf each service(nova, etc) provides OpenAPI spec data via its REST API, consumers can get the corresponding microversioned data by specifying necessary microversion on a request header.\nSo we just need to get multiple OpenAPI spec data for all microversions for each service.\n\nAnother issue is action APIs which share the same URL and Method(POST, PUT, ..) on multiple APIs with different request body. Basically OpenAPI is based on the scenario the pair of URL and Method is represent as a single API. I cannot find a best way to solve this issue at this time. (It is possible to mix multiple action APIs as a single API data, but that would be mess and confused)","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6525,"name":"Gilles Dubreuil","email":"gilles@redhat.com","username":"q-1illes-a"},"change_message_id":"1183fd07c811f974557794a05431b726f2bdd988","unresolved":false,"context_lines":[{"line_number":41,"context_line":"exhaustive and up to date features."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such"},{"line_number":44,"context_line":"as OpenAPI(Swagger), provided there is support for microversions, although that"},{"line_number":45,"context_line":"would have to be discussed and agreed across the OpenStack community."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"All projects under the wings of the api-guide are already providing de-facto but"},{"line_number":48,"context_line":"informal schemas. The initial work requires to use the existing informal API"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_ed9a56c3","line":45,"range":{"start_line":44,"start_character":21,"end_line":45,"end_character":69},"in_reply_to":"df7087c5_5f63fadc","updated":"2018-03-22 09:02:48.000000000","message":"Yes. There is no doubt microversion is not ideal (bad?) for consumers. BTW does anybody care?","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"4db206fe0cd3947b167f8a74f8b0ff5c2d5e2819","unresolved":false,"context_lines":[{"line_number":41,"context_line":"exhaustive and up to date features."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such"},{"line_number":44,"context_line":"as OpenAPI(Swagger), provided there is support for microversions, although that"},{"line_number":45,"context_line":"would have to be discussed and agreed across the OpenStack community."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"All projects under the wings of the api-guide are already providing de-facto but"},{"line_number":48,"context_line":"informal schemas. The initial work requires to use the existing informal API"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_ddb2c049","line":45,"range":{"start_line":44,"start_character":21,"end_line":45,"end_character":69},"in_reply_to":"df7087c5_b2e388a4","updated":"2018-03-21 12:00:50.000000000","message":"\u003e So we just need to get multiple OpenAPI spec data for all microversions for each service.\n\nThis is fine, but if we start generating client libraries from that we\u0027re going to end up with a completely new client library for each microversion.","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"a10182ca146c1a7cd41fd2670867e3d326ecc777","unresolved":false,"context_lines":[{"line_number":41,"context_line":"exhaustive and up to date features."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such"},{"line_number":44,"context_line":"as OpenAPI(Swagger), provided there is support for microversions, although that"},{"line_number":45,"context_line":"would have to be discussed and agreed across the OpenStack community."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"All projects under the wings of the api-guide are already providing de-facto but"},{"line_number":48,"context_line":"informal schemas. The initial work requires to use the existing informal API"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_5f63fadc","line":45,"range":{"start_line":44,"start_character":21,"end_line":45,"end_character":69},"in_reply_to":"df7087c5_ddb2c049","updated":"2018-03-21 18:47:25.000000000","message":"That depends on how to implement client libraries.\nThat means it would be fine to implement a single client library from multiple OpenAPI spec data of multiple microversions.","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"beefce2d38163485e435aea39ecbc60aa597349e","unresolved":false,"context_lines":[{"line_number":41,"context_line":"exhaustive and up to date features."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Another use case would be to allow more standardization for OpenStack APIs, such"},{"line_number":44,"context_line":"as OpenAPI(Swagger), provided there is support for microversions, although that"},{"line_number":45,"context_line":"would have to be discussed and agreed across the OpenStack community."},{"line_number":46,"context_line":""},{"line_number":47,"context_line":"All projects under the wings of the api-guide are already providing de-facto but"},{"line_number":48,"context_line":"informal schemas. The initial work requires to use the existing informal API"}],"source_content_type":"text/x-rst","patch_set":5,"id":"df7087c5_b5fc9b72","line":45,"range":{"start_line":44,"start_character":21,"end_line":45,"end_character":69},"in_reply_to":"df7087c5_ed9a56c3","updated":"2018-03-22 17:16:51.000000000","message":"I don\u0027t think that is bad, there are concrete merits actually.\nBut I agree with that is not ideal with something hard.","commit_id":"6ed692e497643b47d73134662a97d202d8880f30"},{"author":{"_account_id":9311,"name":"Tristan Cacqueray","email":"tdecacqu@redhat.com","username":"tristanC"},"change_message_id":"1cb6212b53c1ccdd56bab594383f977b2a43a181","unresolved":false,"context_lines":[{"line_number":10,"context_line":"Introduction"},{"line_number":11,"context_line":"------------"},{"line_number":12,"context_line":"The initial idea is to provide APIs with API Schema to automate generation of"},{"line_number":13,"context_line":"APIs and help the burden of manually creating SDKs."},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"The current situation"},{"line_number":16,"context_line":"---------------------"}],"source_content_type":"text/x-rst","patch_set":6,"id":"9f6a8fd7_8be3cfa4","line":13,"range":{"start_line":13,"start_character":0,"end_line":13,"end_character":4},"updated":"2018-04-29 01:58:11.000000000","message":"It seems like this should be \"APIs consumer\" or \"APIs client\", otherwise the sentence is pretty confusing :-)","commit_id":"b59d0afff3ae1237f7f471ecdadb00fc7bd79b36"}]}