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 authentification)[/api-authentification] and 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!

Following optional query parameter 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 due to auditability and 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 request is the following exemplary response:

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 exemplary 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 'status' attribute The status is a 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 (ID) of an entities 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 a instance or change¶

Get all attribute values of a specific instance or change of an entity that are 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 needed data of the instance state:

• Meta data of the instance (UTC of state, entity name, instance identifier, type)
• State represent a JSON object with custome specific attributes
• The object difference descripe all changes 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 as delete an instance¶

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

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 "mark-as-deleted" accordingly.

If you need the API from your point of view, just contact us via the feedback function in Versio.io.