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

[Thomas Segismont]

I've created a JIRA to gather and track feedback:
https://issues.jboss.org/browse/HWKMETRICS-302

Feel free to contribute. On JIRA. Or GitHub :)


Le 12/10/2015 09:44, Thomas Segismont a écrit :
> 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 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
>>>
>>> _______________________________________________
>>> 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
>>
>
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>