[Hawkular-dev] Reform Inventory REST API

[Lukas Krejci]

Forgot to answer you compatibility and timing questions...

On Tuesday, May 03, 2016 08:51:35 AM Heiko W.Rupp wrote:
> Hey Lucas,
> 
> I agree that there is room for improvement, as I had to find out by
> using
> inventory via the Ruby Gem.
> 
> What timeline do you have in mind, the changes seem large and will
> probably impact not only inventory, but also the RubyGem (and existing
> code in MiQ), the WF agent, the work of our GSoC students and others,
> that we may not even know of.

This is very high on the list of things to the in the next release.

> Would it make sense to keep the old api in parallel for a while and
> request the new one via different media type or api-root?
>

I think it makes sense to do that. Given we're in 0.x phase of the project I'm 
a little bit reluctant to add "v2" or somesuch to the root though. What about 
instead of prefixing the new API, prefix the old API - that would require 
change in all clients, but a very easy one - instead of "/hawkular/inventory", 
they'd prefix their URLs with "/hawkular/inventory/deprecated"...

> > Here I propose a reformed REST API centered around the canonical
> > paths. It
> 
> I like that - especially for things like GET requests where the CP is
> known
> and all cases of "create something below X", where X can be identified
> by CP.
> I think we already return the CP in all objects, so re-using this in
> subsequent calls
> is good.
> 
> > This is useful for scenarios like "querying all EAPs". The way this
> > would work
> > is that you'd have your resource type that you expect defined and a
> > global
> > level, possibly contained in a metadata pack. You'd then look for
> > resources
> 
> Which we need for such types as EAP.
> 
> > ==== Access Entity By Canonical Path
> > 
> >   /t;tenant_id/f;feed_id/rt;resourceType_id
> 
> Will the '/' in the CP need encoding. If so, I propose to change this
> to a character that does not need url-encoding.
> Otherwise requests get non-human-readable
> 
> GET %2ft;foo%2f;bar..
> 
> Which may get worse for local parts that contain '/' again as in the
> subsystem=datasources/datasource=default case.
> 
> I think it would help me to explicitly write some of those
> cases down (full working curl-command).
> 
> > ==== Accessing Targets of Relationships
> > 
> >   /f;feed_id/r;resource_id/rl;incorporates/type=metric
> 
> I can't say I particularly like it - probably because it is longer
> 
> > This is equivalent to the current
> > `/feeds/feed_id/resources/resource_id/metrics`.
> > 
> >   /f;feed_id/r;resource_id/rl;isParentOf/
> > 
> > (notice the trailing slash)
> 
> This sounds like a constant source of confusion
> 
> > "give me all children of resource with id 'resource_id'".
> > 
> > ==== Accessing Relationships
> > 
> >   /f;feed_id/rl;contains
> > 
> > (notice the lack of trailing slash)
> 
> together with this.
> 
> > "find all the 'contains' relationships going out of the feed with id
> > 'feed_id'."
> > 
> > 
> > result set (to be able to sort or determine the total). We may think
> > about
> > some kind of server-side "live result set" that would hold the results
> > on the
> > server and be accessed using some kind of token (with a TTL). This is
> > how
> > neo4j does it and would avoid having to fetch the full result set on
> > each
> > paged request.
> 
> Sounds good. Do we know though how much paging is currently used?
> Right now in the MiQ use case we don't use it, but that may change in
> the future when we have to pull in hundreds or thousands of servers
> from Hawkular.
> 
> > == POST URLs
> > URI = "/", CP, "/", "resource" | "metric" | "resourceType" | ...;
> 
> SO with a CP starting with '/'
> is this then POST /%2f;bla%2f;tfoo/resource ?
> 
> > The idea here is that you can create the entities only at their
> > canonical
> 
> What is the CP of something that does not exist yet? Or does the above
> represent the to-be parent ? Looks like the latter from the examples
> below.
> 
> > positions. While the Java API allows for creation after a
> > non-canonical
> > traversal, I think this would be unnecessarily complicated for the
> > REST API.
> > The users would pass the familiar blueprint objects to these endpoints
> > as they
> > do currently.
> > 
> > Examples:
> > 
> > /feed - send a feed blueprint and this will create a new feed
> > /resourceType - send a resource type blueprint and it will create a
> > new global
> > resource type
> > /metricType
> > ...
> > /f;feed/resourceType - creates a feed-local resource type
> > 
> > == PUT URLs
> > URI = "/", CP
> > 
> > just send an update object corresponding to the type of entity on the
> > path
> 
> +1
> 
> > == DELETE URLs
> > URI = "/", CP
> 
> +1
> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev

-- 
Lukas Krejci