[Hawkular-dev] Reform Inventory REST API

[Heiko W.Rupp]

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

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