Configuration management database API¶

General¶

The REST API of the Versio.io CMDB allows you to store, update and query instances of an entity.

The following skills will make it easy for you to work with the CMDB API:

• Fundamentals of REST interfaces and a tool for executing REST requests (cURL, browser, SoapUI, etc.). ** API token authentication and the general Versio.io API.
• Understanding the CMDB domain model will help you to use the API better.
• Versio.io is a multi-client system and all requests are only possible in the environment defined by the API token!

The following optional query parameters are available for all CMDB API request types:

Create or update an instance¶

Create or update the state of an entity instance in an environment.

Add the parameter 'utc' to define the time of saving. If you do not use a UTC parameter, the current time will be used. Note that for reasons of auditability, the UTC time must always be after the time of the last update for the instance.

PUT <versio.io-server>/api-versio.db/1.0/<environment>/<entity>/<instanceId>

The following is an example request:

curl --request PUT --header "Content-Type: application/json" \
     -- data '{"myAttribute-1": "myValue-1","myAttribute-2": "myValue-2"}' \
     https://live.versio.io/api-versio.db/1.0/MyEnvironment/MyEntity/MyInstanceID-1?apiToken=yourToken  -d

The result is the following example response:

{
  "saveStatus": "created",
  "lastUpdateUtc": 1585312379822
}

The 'lastUpdateUtc' is the timestamp at which the database saved the instance or change.

The following table lists all return values for the 'saveStatus' attribute. The status is feedback from the Versio.io CMDB on how it evaluates and internally stores the state of the instance.

Read instances and changes¶

Get all entity names¶

Get all existing entity names of the environment.

Add the parameter 'utc' to get the entity names that existed up to that time. All existing environment entity names are returned if the UTC parameter is not used.

GET  /<environment>

The result is an array with all existing entity names up to the given time. Below is an exemplary response:

{
  "items": [
    "entity-A",
    "entity-B",
    "entity-C"
  ]
}

Get all instance identifiers¶

Get all instance identifiers (IDs) of an entity that are managed in the environment.

Add the parameter 'utc' to get the instance identifiers that existed up to that time. All existing instance identifiers are returned if the UTC parameter is not used.

GET /<environment>/<entity-name>

The result is an array with all existing instance identifiers up to the given time. Below is an exemplary response:

{
  "items": [
    "id-1",
    "id-2",
    "id-3"
  ]
}

Get the state of an instance or change¶

Get all attribute values of a specific instance or change of an entity that is managed in the environment.

Add the parameter 'utc' to get the state of the instance for a specific time. Please note that Versio.io determines the state at any given time. You do not necessarily have to specify the time of creation or change.

If you do not use a UTC parameter, the current state of the instance is returned.

GET  /<environment>/<entity>/<instance-id>

In the first object of the items array you get all the necessary data of the instance state:

** Metadata of the instance (UTC of state, entity name, instance identifier, type) ** The state represents a JSON object with customer-specific attributes ** The difference object describes all changes compared to the previous state.

{
  "items": [
    {
      "utc": 1581365957641,
      "entity": "entity-name",
      "instance": "id-1",
      "type": 0,
      "state": {
          ...
          <your change attributes in JSON format>
          ...
          "attribute1":"value1",
          "attribute2":"value2",
          "attribute3": ["a", "b", "c"] 
      },
      "difference": [
        {
          "kind": "N",
          "path": [
            "number"
          ],
          "rhs": 1
        },
        ...
      ]
    }
  ]

Mark an instance as deleted¶

Deleting an instance is not really possible because the Versio.io CMDB guarantees a historicized, revision-safe and auditable database. Therefore, an instance must never be changed or deleted retroactively.

However, it is possible to tell the Versio.io database that the instance of an entity is marked as deleted (see CMDB domain model).

Currently, the REST API is only available internally to Versio.io. The "mark-as-delete" can be defined for each individual entity. This can be configured via the time specification, which indicates the period of time during which no update of an instance has taken place. From this point on, the instance will be "marked as deleted" accordingly.

If you need this API, just contact us via the feedback function in Versio.io.