[Hawkular-dev] Coming to inventory 0.4.0 - bulk create of entities

[Lukas Krejci]

Hi all,

pending a peer-review is a new feature in inventory to support bulk creation 
of entities (in a single transaction).

So far, our REST API was rather granular and concentrated on working with 
single entities or even their individual relationships. This was quite costly 
especially during create, update or delete operations, where the clients would 
need to do stuff one-by-one.

This is being addressed in Inventory 0.4.0 (hopefully coming to Hawkular 
Alpha5) with a new REST endpoint called "/bulk".

For 0.4.0 we will only support bulk creation with update and delete coming in 
the next versions.

The bulk endpoint accepts a rather complex javascript object that can be used 
to specify what is being created and where. The best way to explain it is by 
an example:

{
  "/t;tenant": {
    "environment": [
       {
         "id": "env1", 
         "properties": {"key": "value"}
       },
       {
         "id": "env2", 
         "properties": {"key": "value2"}
       }
    ],
    "resourceType": [
       {
         "id": "URL"         
       }
    ],
    "metricType": [
      {
        "id": "ResponseTime"
      }
    ]   
  },
  "/t;tenant/rt;URL": {
    "data": [
      {
        "role": "configurationSchema",
        "value": {
          "title": "URL config schema",
          "description": "A json schema describing configuration of an URL",
          "type": "string"
        }
      }     
    ],
    "operationType": [
      {
        "id": "ping"
      }
    ]
  },
  "/t;tenant/e;env1": {
    "resource": [
      {
        "id": "url1",
        "resourceTypePath": "/t;tenant/rt;URL" 
      }
    ],
    "metric": [
      {
        "id": "url1_responseTime",
        "metricTypePath": "/t;tenant/mt;ResponseTime"
      }
    ]
  },
  "/t;tenant/e;env1/r;url1": {
    "data": [
      {
        "role": "configuration",
        "value": "http://redhat.com"
      }
    ],
    "relationship": [
      {
        "name": "incorporates",
        "otherEnd": "/t;tenant/e;env1/m;url1_responseTime",
        "direction": "outgoing"
      }
    ]
  }
}

The javascript object above would cause creation of 2 new environments, "env1" 
and "env2", under the tenant "tenant", a new resource type called "URL" and a 
new metric type called "ResponseTime".

When the URL resource type is created, a configuration schema is created for 
it (and the configuration schema prescribes that the configuration of the URL 
is merely a string). Additionally, an operation called "ping" is defined for 
the resource type.

After that a new resource, "url1" is added to environment "env1" with the 
"URL" resource type and a metric called "url1_responseTime" is also added to 
the environment. Finally a configuration is added to the resource and the 
resource is configured to incorporate the previously created metric.

The structure of the javascript object is following:

1) The top-level keys are paths to the inventory entities *under* which the 
new entities should be added, e.g. the first key "/t;tenant" means that the 
value of that key describes what should be created directly under a tenant 
called "tenant". The second key, "/t;tenant/rt;URL", tells the REST API that 
the value of that key describes what should be added "under" that resource 
type.

The structure of what kinds of entities can contain what kinds of entities can 
be found in the documentation [1].

Notice that the order of the keys in the object is significant.

2) The second-level keys describe what type of data to create under a given 
parent (notice that you can create more than 1 type of data under some entity 
types). The values of those keys are arrays of actual blueprint objects 
describing the new entities to be created (each entity type can have different 
format). The blueprint objects are the same as the ones passed in to the 
granular REST endpoints that already exist.


The response always has the 201 - Created status code and is a JSON object 
with the types of entities created as keys and values are again objects with 
keys being the canonical paths to the entities created and values are HTTP 
status codes describing the result of the creation (201, 409, etc.). E.g. for 
the above example the following would be a response:

{
  "environment": {
    "/t;tenant/e;env1": 201,
    "/t;tenant/e;env2": 201
  },
  "resourceType": {
    "/t;tenant/rt;URL": 201
  }
  "metricType": {
    "/t;tenant/mt;ResponseTime": 201
  },
  "data": {
    "/t;tenant/rt;URL/d;configurationSchema": 201,
    "/t;tenant/e;env1/r;url1/d;configuration": 201
  },
  "operationType": {
    "/t;tenant/rt;URL/ot;ping": 201
  },
  "resource": {
    "/t;tenant/e;env1/r;url1": 201
  },
  "metric": {
    "/t;tenant/e;env1/m;url1_responseTime": 201
  },
  "relationship": {
    "<some-random-id>": 201
  }
}

Hope you will find this useful,

Lukas

[1] http://www.hawkular.org/docs/components/inventory/index.html#inventory-organization