Hi, Currently our REST API documentation is generated solely from Swagger annotations. This is a good starting point, but I believe it's not enough nor easy for new users. I filed this JIRA: HWKMETRICS-297 Incorporate static blocks into the REST API documentation https://issues.jboss.org/browse/HWKMETRICS-297 And started the PR: https://github.com/hawkular/hawkular-metrics/pull/389 Here's what I have in mind: - provide general information which does not fit in annotations into a base Asciidoc file - merge the static file with the Swagger generated one Many services organize their REST API documentation similarly (I liked GitHub and PagerDuty examples in particular). I need your opinion on the static file plan. I started with this: https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... Can you think of anything missing? Or do you have any comments? Of course the result doc is not perfect, but it's a step forward. Thanks, Thomas _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

I've updated the base documentation: https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... Attached is a sample of the merge result (base documentation + swagger). If you've ever felt short of information when using the Metrics REST API, this is an opportunity to chime in for improvements. Le 07/10/2015 10:48, Thomas Heute a écrit : > Agreed on general information ! > > I would like us to break some barriers between components. > There are likely notions that should to be shared and shouldn't be just > copied over and over. (Obvious ones are Tenant and Timestamps) > > So I would like to see the APIs in a single page (like Pager Duty) with > general information followed by Metrics, Alerts,... sections. > > > > On Tue, Oct 6, 2015 at 3:45 PM, Thomas Segismont <tsegismo(a)redhat.com > <mailto:tsegismo@redhat.com>> wrote: > > Hi, > > Currently our REST API documentation is generated solely from Swagger > annotations. > > This is a good starting point, but I believe it's not enough nor easy > for new users. > > I filed this JIRA: > > HWKMETRICS-297 Incorporate static blocks into the REST API > documentation > https://issues.jboss.org/browse/HWKMETRICS-297 > > And started the PR: > https://github.com/hawkular/hawkular-metrics/pull/389 > > Here's what I have in mind: > - provide general information which does not fit in annotations into a > base Asciidoc file > - merge the static file with the Swagger generated one > > Many services organize their REST API documentation similarly (I liked > GitHub and PagerDuty examples in particular). > > I need your opinion on the static file plan. I started with this: > https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... > > Can you think of anything missing? Or do you have any comments? > > Of course the result doc is not perfect, but it's a step forward. > > Thanks, > Thomas > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> > https://lists.jboss.org/mailman/listinfo/hawkular-dev > > > > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

Le 07/10/2015 14:56, Gary Brown a écrit : > Content looks good. Is there going to be an index to help navigation of the document? Thanks! Yes, the index will be generated by jBake the Asciidoc source is merged in to the website repo.

In general more concrete examples such as curl commands would be tremendously helpful.

1. Explain 'start' and 'end' time range concept a bit more, Not everyone knows it is epoch in millisecond. A visual explanation of raw vs aggregation data would be nice: x X x x x x X x x raw data ^start ^end -> now

2. How to use tags. Ex: tags=tagName:regexp,tagNameB:regexp

3. An online sandbox to try out different api calls (similar to https://jsfiddle.net/)

----- Original Message ----- From: "Thomas Segismont" <tsegismo(a)redhat.com&gt; To: hawkular-dev(a)lists.jboss.org Sent: Wednesday, October 7, 2015 5:45:28 AM Subject: Re: [Hawkular-dev] [Metrics] Better REST API documentation, feedback needed I've updated the base documentation: https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... Attached is a sample of the merge result (base documentation + swagger). If you've ever felt short of information when using the Metrics REST API, this is an opportunity to chime in for improvements. Le 07/10/2015 10:48, Thomas Heute a écrit : > Agreed on general information ! > > I would like us to break some barriers between components. > There are likely notions that should to be shared and shouldn't be just > copied over and over. (Obvious ones are Tenant and Timestamps) > > So I would like to see the APIs in a single page (like Pager Duty) with > general information followed by Metrics, Alerts,... sections. > > > > On Tue, Oct 6, 2015 at 3:45 PM, Thomas Segismont <tsegismo(a)redhat.com > <mailto:tsegismo@redhat.com>> wrote: > > Hi, > > Currently our REST API documentation is generated solely from Swagger > annotations. > > This is a good starting point, but I believe it's not enough nor easy > for new users. > > I filed this JIRA: > > HWKMETRICS-297 Incorporate static blocks into the REST API documentation > https://issues.jboss.org/browse/HWKMETRICS-297 > > And started the PR: > https://github.com/hawkular/hawkular-metrics/pull/389 > > Here's what I have in mind: > - provide general information which does not fit in annotations into a > base Asciidoc file > - merge the static file with the Swagger generated one > > Many services organize their REST API documentation similarly (I liked > GitHub and PagerDuty examples in particular). > > I need your opinion on the static file plan. I started with this: > https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... > > Can you think of anything missing? Or do you have any comments? > > Of course the result doc is not perfect, but it's a step forward. > > Thanks, > Thomas > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> > https://lists.jboss.org/mailman/listinfo/hawkular-dev > > > > > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev

And thanks for the feedback Viet! Le 12/10/2015 09:44, Thomas Segismont a écrit : > Le 09/10/2015 19:35, Viet Nguyen a écrit : >> In general more concrete examples such as curl commands would be tremendously helpful. > > +1 > > The most important examples I can think of: > - POST requests for new data > - GET requests for data > - GET requests for stats > - Tagging samples > - Find by tags samples > >> >> 1. Explain 'start' and 'end' time range concept a bit more, Not everyone knows it is epoch in millisecond. A visual explanation of raw vs aggregation data would be nice: >> >> x X x x x x X x x raw data >> ^start ^end -> now >> > > Did you look at the latest version? In the "Time Ranges" section, > there's a cross-reference to the "Timestamps" section, which clearly > explains how Metrics understands timestamps. > > +1 for visual explanations. But I'm not sure I get what you meant with > the schema. > >> >> 2. How to use tags. Ex: tags=tagName:regexp,tagNameB:regexp >> > > I suppose the examples mentioned above would do this. > >> >> 3. An online sandbox to try out different api calls (similar to https://jsfiddle.net/) >> > > You mean prepare javascript files for testing? > Or having a public server for testing? > >> >> >> >> ----- Original Message ----- >> From: "Thomas Segismont" <tsegismo(a)redhat.com&gt; >> To: hawkular-dev(a)lists.jboss.org >> Sent: Wednesday, October 7, 2015 5:45:28 AM >> Subject: Re: [Hawkular-dev] [Metrics] Better REST API documentation, feedback needed >> >> I've updated the base documentation: >> >> https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... >> >> Attached is a sample of the merge result (base documentation + swagger). >> >> If you've ever felt short of information when using the Metrics REST >> API, this is an opportunity to chime in for improvements. >> >> Le 07/10/2015 10:48, Thomas Heute a écrit : >>> Agreed on general information ! >>> >>> I would like us to break some barriers between components. >>> There are likely notions that should to be shared and shouldn't be just >>> copied over and over. (Obvious ones are Tenant and Timestamps) >>> >>> So I would like to see the APIs in a single page (like Pager Duty) with >>> general information followed by Metrics, Alerts,... sections. >>> >>> >>> >>> On Tue, Oct 6, 2015 at 3:45 PM, Thomas Segismont <tsegismo(a)redhat.com >>> <mailto:tsegismo@redhat.com>> wrote: >>> >>> Hi, >>> >>> Currently our REST API documentation is generated solely from Swagger >>> annotations. >>> >>> This is a good starting point, but I believe it's not enough nor easy >>> for new users. >>> >>> I filed this JIRA: >>> >>> HWKMETRICS-297 Incorporate static blocks into the REST API documentation >>> https://issues.jboss.org/browse/HWKMETRICS-297 >>> >>> And started the PR: >>> https://github.com/hawkular/hawkular-metrics/pull/389 >>> >>> Here's what I have in mind: >>> - provide general information which does not fit in annotations into a >>> base Asciidoc file >>> - merge the static file with the Swagger generated one >>> >>> Many services organize their REST API documentation similarly (I liked >>> GitHub and PagerDuty examples in particular). >>> >>> I need your opinion on the static file plan. I started with this: >>> https://raw.githubusercontent.com/tsegismont/hawkular-metrics/jira/HWKMET... >>> >>> Can you think of anything missing? Or do you have any comments? >>> >>> Of course the result doc is not perfect, but it's a step forward. >>> >>> Thanks, >>> Thomas >>> >>> _______________________________________________ >>> hawkular-dev mailing list >>> hawkular-dev(a)lists.jboss.org <mailto:hawkular-dev@lists.jboss.org> >>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>> >>> >>> >>> >>> >>> _______________________________________________ >>> hawkular-dev mailing list >>> hawkular-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/hawkular-dev >>> >> >> >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hawkular-dev >> >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hawkular-dev >> > > _______________________________________________ > hawkular-dev mailing list > hawkular-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hawkular-dev > _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev