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

[Viet Nguyen]

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 at redhat.com>
To: hawkular-dev at 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/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc

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 at redhat.com
> <mailto:tsegismo at 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/HWKMETRICS-297/api/metrics-api-jaxrs/src/main/rest-doc/base.adoc
>
>     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 at lists.jboss.org <mailto:hawkular-dev at lists.jboss.org>
>     https://lists.jboss.org/mailman/listinfo/hawkular-dev
>
>
>
>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>


_______________________________________________
hawkular-dev mailing list
hawkular-dev at lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hawkular-dev