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

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