[Hawkular-dev] metrics: REST API evolution when querying for multiple metrics

[Joel Takvorian]

Hello,

Following the discussions here:
https://github.com/hawkular/hawkular-metrics/pull/584 I would like to bring
that up:

---------
The problem
I came to some limitation of the current REST API of hawkular-metrics when
adding features to the Grafana plugin. The main point here is that because
of an issue in Grafana (and/or golang) which you've certainly already
discussed before I join, we're limited in the use of @get endpoints when
metric ids are sent as query parameters. Although it has already been
solved in the current version of the grafana plugin, the problem reappears
when I'm trying to add features.

But beside those grafana centric considerations I think that it could be a
good occasion to bring more consistency to the REST API when querying data
for multiple metrics. There's several endpoints that, in my opinion, could
be harmonized.

-----
So what's missing?

(note, by "*" I mean "gauges", "counters", "availability" or "string" ; not
"metrics". When I write "/raw", same applies for "/rate".)

- Some endpoints like "@get */stats" allow to query by list of ids or list
of tags, but there's no equivalent on "@get */raw", and the "@post
*/raw/query" doesn't handle tags
Note that I've already opened a JIRA ticket for query-by-tag
generalization: https://issues.jboss.org/browse/HWKMETRICS-466 . I can't
find any good reason why we could do it when querying stats, but not when
querying raw data.

- On the other hand, endpoints like "@post */raw/query", used for grafana,
has no equivalent for "stats". I would really like to have this one for
Grafana.

- List of metrics sometimes referred as "ids" (class QueryRequest),
sometimes "metrics" (all @get query params). We could add "metrics" in
QueryRequest but keep/deprecate "ids" for compatibility?

-----
Suggestions:

1st Option: keep the API in the current form and bring all endpoints up to
the same level of functionality, that is:
  * Create "@get */raw" that can take ids or tags
  * Make "@post */raw/query" understand tags
  * Create "@post */stats/query" that can take ids or tags

---
2d Option: change the current model to dissociate query by ids or by tags
Basically the idea is to provide different path if we want to query by ids
or by tags, to avoid having the assertion we currently have "must provide
either ids or tags but not both". I think it's cleaner to separate them. Of
course it has the downside of breaking (making deprecated) all query-by-tag
in the current API.

So, queries by ids would be the default one:
  * "@get */raw"
  * "@get */stats"
  * "@post */raw/query"
  * "@post */stats/query"
None of them would accept tags

And query by tag would be:
  * "@get */raw/tags" (or "*/raw/tags/{tags}" ?)
  * "@get */stats/tags"
  * "@post */raw/tags/query"
  * "@post */stats/tags/query"
None of them would accept ids

---
Other Option?


=> Personally, given the downside of the 2/ I would rather go for the 1st
one.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/hawkular-dev/attachments/20160914/2a2f636d/attachment.html