Re: [Hawkular-dev] [Metrics] Better REST API documentation, feedback needed

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