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

[Lucas Ponce]

A side comment.

If we are going to suggest strong changes on API I think it could be a good moment to hold them and install a strong versioning mechanism on the REST API across the components.

So, in that way, it could be for a user to maintain old APIs and new ones.

They way to do this can be discussed and get some consensus, but I guess we should be aligned (inventory, metrics, alerting) here.

Lucas

----- Mensaje original -----
> De: "Joel Takvorian" <jtakvori at redhat.com>
> Para: "Discussions around Hawkular development" <hawkular-dev at lists.jboss.org>
> Enviados: Miércoles, 14 de Septiembre 2016 10:42:50
> Asunto: [Hawkular-dev] metrics: REST API evolution when querying for	multiple metrics
> 
> 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.
> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>