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>
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