[Hawkular-dev] Reform Inventory REST API

[Lukas Krejci]

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.
> 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?
> 
> > 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..
> 

No, that would literally be:

  GET /t;foo/f;bar

If a segment of a path already contained a forward slash, only that'd need to 
be encoded (and would return encoded in responses from inventory).

I.e. if you were creating a resource with a slash, you'd do a post:

  POST /t;foo/f;bar/r;my-parent
  {
     "id" : "subsystem=datasources/datasource=default",
     ...
  }

You'd get a location back in headers:

  Location: /hawkular/inventory/t;foo/f;bar/r;my-
parent/subsystem%3Ddatasources%2Fdatasource%3Ddefault

If you chop off "/hawkular/inventory" from that location you get the canonical 
path of your new entity (which you also obtain in the JSON response of the 
post request).

You don't need to do any additional encoding of that - just concatenate it to 
the URL you're building next.. Inventory encodes the CPs in URI-safe manner 
(took me a while to get there, but I think we do that correctly now).


> 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
> 

Yeah, me neither - but it's the cost of the additional flexibility we're 
adding here. You'd use the very same pattern if you'd want to ask for your 
custom relationship called "mummy" (or "critical" or whatever) - for that the 
current REST API is way more cumbersome.

Currently, you'd have to list all the relationships of the resource, find the 
IDs of the relationships with the "mummy" name, do another N requests to get 
the details of those relationship to find out their targets targets and then 
do another N requests to get the details of those targets.


> > 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.

Yes... I need to take a look at the grammar if adding "/entities" (instead of 
the "/") and "/relationships" (instead of no "/") doesn't give rise to some 
ambiguities - gut feeling is that it doesn't.

> 
> > "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.
> 

Paging was a specific request of the (old) UI which uses it heavily in all the 
inventory-based listings.

> > == POST URLs
> > URI = "/", CP, "/", "resource" | "metric" | "resourceType" | ...;
> 
> SO with a CP starting with '/'
> is this then POST /%2f;bla%2f;tfoo/resource ?
>

No, that'd literally be:

  POST /;bla/;tfoo/resource

which is an invalid CP ;), but you get the point - the CPs as they are encoded 
by inventory are already URI-safe and can just be concatenated to a URL, no 
need for escaping.

> > 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.
> 

Yes, POST /cp-of-the-parent/type-of-new-entity

> > 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