Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-25 Thread GHANSHYAM MANN
Hi Ken'ichi, Nice idea.

On Wed, Aug 26, 2015 at 11:36 AM, Ken'ichi Ohmichi
ken1ohmi...@gmail.com wrote:
 Hi Anne, Nova API guys,

 I'd like to explain how to generate API docs from Tempest log.

 In Tempest, each API test contains UUID for the test identification now.
 Current my idea is to parse tempest log, create a patch based on the
 parsing and post a patch to each project repo like:

 1. Each project like Nova
   Contain the combinations of both generic API name(create a server,
 etc.) and test UUID of Tempest
 2. Tempest
   * Output test UUIDs to Tempest log for each API operation
   * Contain **Script A** to parse Tempest log for getting URL,
 headers, request body, response body and normal status code based on
 the specified test UUID
   * Contain **Script B** to get the above combinations from each
 project repo via external plugin interfaces[1], run **Script A** with
 each test UUID and create API samples for each generic API name.

And for Project out of Tempest scope can provide tests UUID from their
Tempest like tests. And doc thing can be served for them via Tempest
external plugin design.

 3. Bot of openstack-infra
   * Create an API sample patch for each project and post it if the
 sample doesn't exist in the repo.

 Even after this way is implemented, the descriptions of request
 parameters are not covered on api docs:
 But each project will be able to get them with each project own way
 like Pecan/WSME docstring, JSON-Schema or by hands.

or we can get each param doc string from project via external plugin
in step 2 along with API generic name
with assumption that each project should have doc string for each API
request param.

Just wondering how we will do that for all microversions as Tempest
would not be having tests for all microversions.


 Any thought?

 Thanks
 Ken Ohmichi
 ---
 [1]: 
 http://specs.openstack.org/openstack/qa-specs/specs/tempest-external-plugin-interface.html

 2015-08-26 10:36 GMT+09:00 Ken'ichi Ohmichi ken1ohmi...@gmail.com:
 Hi Anne,

 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@justwriteclick.com:
 Hi all,

 I'm writing to find out how teams keep API sample requests and responses
 up-to-date. I know the nova team has a sample generator [1] that they've
 maintained for a few years now. Do other teams have something similar? If
 so, is your approach like the nova one?

 We had a weekly IRC meeting of Nova API yesterday(today for some
 guys), and we discussed how to generate/maintain API docs in long
 term.
 After the discussion, I have an idea.

 How about generating API sample files from Tempest log files?

 Now Tempest is writing most necessary parts of API docs((URL, headers,
 request body, response body, http status code) to its own log file
 like:

 http://logs.openstack.org/88/207688/3/check/gate-tempest-dsvm-full/d7a79d1/logs/tempest.txt.gz#_2015-08-10_13_20_36_982

 2015-08-10 13:20:36.982 [..] 202 POST
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers
 0.920s
 2015-08-10 13:20:36.983 [..] Request - Headers: {'Content-Type':
 'application/json', 'X-Auth-Token': 'omitted', 'Accept':
 'application/json'}
 Body: {server: {name:
 tempest.common.compute-instance-607936499, networks: [{uuid:
 e63068c6-99d5-41f5-804d-ccb812bfeb51}], imageRef:
 d4159c59-cbfb-43f1-94de-3552d1f2871e, flavorRef: 42}}
 Response - Headers: {'location':
 'http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c',
 'content-type': 'application/json', 'date': 'Mon, 10 Aug 2015 13:20:36
 GMT', 'x-compute-request-id':
 'req-0fa22034-c1d5-41b2-bfb9-6de533733290', 'connection': 'close',
 'status': '202', 'content-length': '434'}
 Body: {server: {security_groups: [{name: default}],
 OS-DCF:diskConfig: MANUAL, id:
 19f98a6f-26d2-4491-93a8-8e894f19034c, links: [{href:
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: self}, {href:
 http://127.0.0.1:8774/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: bookmark}], adminPass: 2iEDo2EP5wRM}} _log_request_full
 /opt/stack/new/tempest/.tox/full/local/lib/python2.7/site-packages/tempest_lib/common/rest_client.py:411

 I feel it is difficult to implement the similar sample test way of
 Nova on each project.
 The above Tempest log is written on tempest-lib side and that is
 common way between projects.
 So we can use this way for all projects as a common/consistent way, I
 imagine now.

 I will make/write the detail of this idea later.

 Thanks
 Ken Ohmichi

 ---

 1.
 https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py

 --
 Anne Gentle
 Rackspace
 Principal Engineer
 www.justwriteclick.com

 __
 OpenStack Development Mailing List (not for usage questions)
 Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 

Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-25 Thread Ken'ichi Ohmichi
Hi Anne, Nova API guys,

I'd like to explain how to generate API docs from Tempest log.

In Tempest, each API test contains UUID for the test identification now.
Current my idea is to parse tempest log, create a patch based on the
parsing and post a patch to each project repo like:

1. Each project like Nova
  Contain the combinations of both generic API name(create a server,
etc.) and test UUID of Tempest
2. Tempest
  * Output test UUIDs to Tempest log for each API operation
  * Contain **Script A** to parse Tempest log for getting URL,
headers, request body, response body and normal status code based on
the specified test UUID
  * Contain **Script B** to get the above combinations from each
project repo via external plugin interfaces[1], run **Script A** with
each test UUID and create API samples for each generic API name.
3. Bot of openstack-infra
  * Create an API sample patch for each project and post it if the
sample doesn't exist in the repo.

Even after this way is implemented, the descriptions of request
parameters are not covered on api docs:
But each project will be able to get them with each project own way
like Pecan/WSME docstring, JSON-Schema or by hands.

Any thought?

Thanks
Ken Ohmichi
---
[1]: 
http://specs.openstack.org/openstack/qa-specs/specs/tempest-external-plugin-interface.html

2015-08-26 10:36 GMT+09:00 Ken'ichi Ohmichi ken1ohmi...@gmail.com:
 Hi Anne,

 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@justwriteclick.com:
 Hi all,

 I'm writing to find out how teams keep API sample requests and responses
 up-to-date. I know the nova team has a sample generator [1] that they've
 maintained for a few years now. Do other teams have something similar? If
 so, is your approach like the nova one?

 We had a weekly IRC meeting of Nova API yesterday(today for some
 guys), and we discussed how to generate/maintain API docs in long
 term.
 After the discussion, I have an idea.

 How about generating API sample files from Tempest log files?

 Now Tempest is writing most necessary parts of API docs((URL, headers,
 request body, response body, http status code) to its own log file
 like:

 http://logs.openstack.org/88/207688/3/check/gate-tempest-dsvm-full/d7a79d1/logs/tempest.txt.gz#_2015-08-10_13_20_36_982

 2015-08-10 13:20:36.982 [..] 202 POST
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers
 0.920s
 2015-08-10 13:20:36.983 [..] Request - Headers: {'Content-Type':
 'application/json', 'X-Auth-Token': 'omitted', 'Accept':
 'application/json'}
 Body: {server: {name:
 tempest.common.compute-instance-607936499, networks: [{uuid:
 e63068c6-99d5-41f5-804d-ccb812bfeb51}], imageRef:
 d4159c59-cbfb-43f1-94de-3552d1f2871e, flavorRef: 42}}
 Response - Headers: {'location':
 'http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c',
 'content-type': 'application/json', 'date': 'Mon, 10 Aug 2015 13:20:36
 GMT', 'x-compute-request-id':
 'req-0fa22034-c1d5-41b2-bfb9-6de533733290', 'connection': 'close',
 'status': '202', 'content-length': '434'}
 Body: {server: {security_groups: [{name: default}],
 OS-DCF:diskConfig: MANUAL, id:
 19f98a6f-26d2-4491-93a8-8e894f19034c, links: [{href:
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: self}, {href:
 http://127.0.0.1:8774/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: bookmark}], adminPass: 2iEDo2EP5wRM}} _log_request_full
 /opt/stack/new/tempest/.tox/full/local/lib/python2.7/site-packages/tempest_lib/common/rest_client.py:411

 I feel it is difficult to implement the similar sample test way of
 Nova on each project.
 The above Tempest log is written on tempest-lib side and that is
 common way between projects.
 So we can use this way for all projects as a common/consistent way, I
 imagine now.

 I will make/write the detail of this idea later.

 Thanks
 Ken Ohmichi

 ---

 1.
 https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py

 --
 Anne Gentle
 Rackspace
 Principal Engineer
 www.justwriteclick.com

 __
 OpenStack Development Mailing List (not for usage questions)
 Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-25 Thread Ken'ichi Ohmichi
2015-08-26 12:15 GMT+09:00 GHANSHYAM MANN ghanshyamm...@gmail.com:
 Hi Ken'ichi, Nice idea.

 On Wed, Aug 26, 2015 at 11:36 AM, Ken'ichi Ohmichi
 ken1ohmi...@gmail.com wrote:
 Hi Anne, Nova API guys,

 I'd like to explain how to generate API docs from Tempest log.

 In Tempest, each API test contains UUID for the test identification now.
 Current my idea is to parse tempest log, create a patch based on the
 parsing and post a patch to each project repo like:

 1. Each project like Nova
   Contain the combinations of both generic API name(create a server,
 etc.) and test UUID of Tempest
 2. Tempest
   * Output test UUIDs to Tempest log for each API operation
   * Contain **Script A** to parse Tempest log for getting URL,
 headers, request body, response body and normal status code based on
 the specified test UUID
   * Contain **Script B** to get the above combinations from each
 project repo via external plugin interfaces[1], run **Script A** with
 each test UUID and create API samples for each generic API name.

 And for Project out of Tempest scope can provide tests UUID from their
 Tempest like tests. And doc thing can be served for them via Tempest
 external plugin design.

yeah, +1 for enabling this way for outside-Tempest projects also.

 3. Bot of openstack-infra
   * Create an API sample patch for each project and post it if the
 sample doesn't exist in the repo.

 Even after this way is implemented, the descriptions of request
 parameters are not covered on api docs:
 But each project will be able to get them with each project own way
 like Pecan/WSME docstring, JSON-Schema or by hands.

 or we can get each param doc string from project via external plugin
 in step 2 along with API generic name
 with assumption that each project should have doc string for each API
 request param.

nice idea, we can make a rule where the script for extracting request params
explanation and use it on step2 :)

 Just wondering how we will do that for all microversions as Tempest
 would not be having tests for all microversions.

Oh, nice point.
I feel it is good to avoid duplicated sample files in Nova if the APIs
are not different between microversions.
We need to implement microversion tests on tempest before anyway.

Thanks
Ken Ohmichi

---

 ---
 [1]: 
 http://specs.openstack.org/openstack/qa-specs/specs/tempest-external-plugin-interface.html

 2015-08-26 10:36 GMT+09:00 Ken'ichi Ohmichi ken1ohmi...@gmail.com:
 Hi Anne,

 2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@justwriteclick.com:
 Hi all,

 I'm writing to find out how teams keep API sample requests and responses
 up-to-date. I know the nova team has a sample generator [1] that they've
 maintained for a few years now. Do other teams have something similar? If
 so, is your approach like the nova one?

 We had a weekly IRC meeting of Nova API yesterday(today for some
 guys), and we discussed how to generate/maintain API docs in long
 term.
 After the discussion, I have an idea.

 How about generating API sample files from Tempest log files?

 Now Tempest is writing most necessary parts of API docs((URL, headers,
 request body, response body, http status code) to its own log file
 like:

 http://logs.openstack.org/88/207688/3/check/gate-tempest-dsvm-full/d7a79d1/logs/tempest.txt.gz#_2015-08-10_13_20_36_982

 2015-08-10 13:20:36.982 [..] 202 POST
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers
 0.920s
 2015-08-10 13:20:36.983 [..] Request - Headers: {'Content-Type':
 'application/json', 'X-Auth-Token': 'omitted', 'Accept':
 'application/json'}
 Body: {server: {name:
 tempest.common.compute-instance-607936499, networks: [{uuid:
 e63068c6-99d5-41f5-804d-ccb812bfeb51}], imageRef:
 d4159c59-cbfb-43f1-94de-3552d1f2871e, flavorRef: 42}}
 Response - Headers: {'location':
 'http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c',
 'content-type': 'application/json', 'date': 'Mon, 10 Aug 2015 13:20:36
 GMT', 'x-compute-request-id':
 'req-0fa22034-c1d5-41b2-bfb9-6de533733290', 'connection': 'close',
 'status': '202', 'content-length': '434'}
 Body: {server: {security_groups: [{name: default}],
 OS-DCF:diskConfig: MANUAL, id:
 19f98a6f-26d2-4491-93a8-8e894f19034c, links: [{href:
 http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: self}, {href:
 http://127.0.0.1:8774/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
 rel: bookmark}], adminPass: 2iEDo2EP5wRM}} _log_request_full
 /opt/stack/new/tempest/.tox/full/local/lib/python2.7/site-packages/tempest_lib/common/rest_client.py:411

 I feel it is difficult to implement the similar sample test way of
 Nova on each project.
 The above Tempest log is written on tempest-lib side and that is
 common way between projects.
 So we can use this way for all projects as a common/consistent way, I
 imagine now.

 I will make/write the detail of this idea 

Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-25 Thread michael mccune

On 08/24/2015 11:51 AM, Anne Gentle wrote:

Hi all,

I'm writing to find out how teams keep API sample requests and responses
up-to-date. I know the nova team has a sample generator [1] that they've
maintained for a few years now. Do other teams have something similar?
If so, is your approach like the nova one?


sahara keeps examples for some of it's calls in our repo, although they 
are not a full example of all calls. these have all been hand-crafted, 
and could use some updating to add examples for the missing calls.


we are currently evaluating a new major version for our api[1], and are 
talking about creating an api directory in our specs repo to have more 
up-to-date samples, and a descriptive explanation, of our api. i'm 
guessing that initially these examples will be hand-crafted.



regards,
mike

[1]: https://review.openstack.org/#/c/212172/

__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-25 Thread Ken'ichi Ohmichi
Hi Anne,

2015-08-25 0:51 GMT+09:00 Anne Gentle annegen...@justwriteclick.com:
 Hi all,

 I'm writing to find out how teams keep API sample requests and responses
 up-to-date. I know the nova team has a sample generator [1] that they've
 maintained for a few years now. Do other teams have something similar? If
 so, is your approach like the nova one?

We had a weekly IRC meeting of Nova API yesterday(today for some
guys), and we discussed how to generate/maintain API docs in long
term.
After the discussion, I have an idea.

How about generating API sample files from Tempest log files?

Now Tempest is writing most necessary parts of API docs((URL, headers,
request body, response body, http status code) to its own log file
like:

http://logs.openstack.org/88/207688/3/check/gate-tempest-dsvm-full/d7a79d1/logs/tempest.txt.gz#_2015-08-10_13_20_36_982

2015-08-10 13:20:36.982 [..] 202 POST
http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers
0.920s
2015-08-10 13:20:36.983 [..] Request - Headers: {'Content-Type':
'application/json', 'X-Auth-Token': 'omitted', 'Accept':
'application/json'}
Body: {server: {name:
tempest.common.compute-instance-607936499, networks: [{uuid:
e63068c6-99d5-41f5-804d-ccb812bfeb51}], imageRef:
d4159c59-cbfb-43f1-94de-3552d1f2871e, flavorRef: 42}}
Response - Headers: {'location':
'http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c',
'content-type': 'application/json', 'date': 'Mon, 10 Aug 2015 13:20:36
GMT', 'x-compute-request-id':
'req-0fa22034-c1d5-41b2-bfb9-6de533733290', 'connection': 'close',
'status': '202', 'content-length': '434'}
Body: {server: {security_groups: [{name: default}],
OS-DCF:diskConfig: MANUAL, id:
19f98a6f-26d2-4491-93a8-8e894f19034c, links: [{href:
http://127.0.0.1:8774/v2/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
rel: self}, {href:
http://127.0.0.1:8774/c2ab3e6ac69e43bb925a4895075e47d7/servers/19f98a6f-26d2-4491-93a8-8e894f19034c;,
rel: bookmark}], adminPass: 2iEDo2EP5wRM}} _log_request_full
/opt/stack/new/tempest/.tox/full/local/lib/python2.7/site-packages/tempest_lib/common/rest_client.py:411

I feel it is difficult to implement the similar sample test way of
Nova on each project.
The above Tempest log is written on tempest-lib side and that is
common way between projects.
So we can use this way for all projects as a common/consistent way, I
imagine now.

I will make/write the detail of this idea later.

Thanks
Ken Ohmichi

---

 1.
 https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py

 --
 Anne Gentle
 Rackspace
 Principal Engineer
 www.justwriteclick.com

 __
 OpenStack Development Mailing List (not for usage questions)
 Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [api] [docs] Generating API samples

2015-08-24 Thread Morgan Fainberg
Keystone doesn't use anything similar to sample requests at this time. Though I 
am sure there wouldn't be much opposition to it provided there was someone 
stepping up to do the work. 

Sent via mobile

 On Aug 24, 2015, at 08:51, Anne Gentle annegen...@justwriteclick.com wrote:
 
 Hi all, 
 
 I'm writing to find out how teams keep API sample requests and responses 
 up-to-date. I know the nova team has a sample generator [1] that they've 
 maintained for a few years now. Do other teams have something similar? If so, 
 is your approach like the nova one?
 
 Thanks,
 Anne
 
 
 1. 
 https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py
  
 
 -- 
 Anne Gentle
 Rackspace
 Principal Engineer
 www.justwriteclick.com
 __
 OpenStack Development Mailing List (not for usage questions)
 Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


[openstack-dev] [api] [docs] Generating API samples

2015-08-24 Thread Anne Gentle
Hi all,

I'm writing to find out how teams keep API sample requests and responses
up-to-date. I know the nova team has a sample generator [1] that they've
maintained for a few years now. Do other teams have something similar? If
so, is your approach like the nova one?

Thanks,
Anne


1.
https://github.com/openstack/nova/blob/master/nova/tests/functional/api_sample_tests/api_sample_base.py


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev