Skip to main content

Preface

Qbilon provides a simple schema API that allows users to interact with the schema of imported data. The schema API can read schema data from Qbilon, delete existing schema data with cascading effects on their respective instances and create new schema data. It can also alter existing schema data by adding or removing attributes from types and relations, which has cascading effects on instance data. To this end, the schema data endpoint /apiv1/schema can be used.

Endpoints

Users who want to create, read or delete schema data can interact with the following endpoints using the relevant HTTP methods:
  • Read schema → GET https://host/apiv1/schema
  • Write schema → POST https://host/apiv1/schema
  • Delete schema → POST https://host/apiv1/schema/delete
  • Create attribute → PUT https://host/apiv1/schema?:attributeName&:dataType&:ownerId
  • Delete attribute → DELETE https://host/apiv1/schema?:attributeName&:ownerId
The host part is the domain of your Qbilon instance. For attribute operations, the attributeName is the name of the attribute as shown in the Qbilon data schema view. The dataType is one of the allowed data types in Qbilon — see the Writing in Qbilon section “Datatypes”. The ownerId is the base64-encoded, unique “id” of the asset type, which you can retrieve via the read schema endpoint.

Reading Schema Data

When you request schema data from Qbilon via the aforementioned REST endpoint, you will receive a data format similar to the following:
The response will always contain the fields types and relations, which will contain all types and relations currently available in Qbilon, if present. The name of each type and relation is unique and is therefore used as a key to access additional information:
  • id: unique ID for that type or relation (needed, for example, for attribute operations).
  • attributes: Key-value entries with the name and data type of each attribute for this type/relation.
  • dataSources: A list of the names of all data sources that contributed data to one or more instances of that type/relation.
  • numberInstances: The number of instances of that type/relation currently existing within Qbilon.

Writing Schema Data

To create a new type or relation (with or without attributes) within Qbilon, send a request body similar to the one below to the aforementioned REST endpoint.
The data format is similar to the one you received from the GET endpoint. However, it allows you to skip unnecessary or impermissible parts of a write request to the schema endpoint. For example, you can skip the system properties ID, FirstSeen, and LastSeen because they will be created automatically. It does not make sense to specify the number of instances for an empty type or relation. To create instances of that type, take a look at Writing in Qbilon. Relation names must conform to the Qbilon relation format, i.e., <Relation Name> [<Source Type> → <Target Type>]. Also, the source and target types must either already exist within Qbilon or be part of the same write request.

Deleting Schema Data

To delete an existing type or relation (with or without attributes) from Qbilon, send a request body similar to the one below to the aforementioned REST endpoint.
Providing a list of the respective type/relation names that should be deleted is sufficient. Note that misspelled type or relation names will be ignored by Qbilon without generating an error. Also, note that deleting a type or relation also deletes all of its instances within Qbilon. You can think of it as dropping a table in relational databases.

Creating/Deleting Attributes

To create or delete single attributes on existing types/relations, use the aforementioned endpoint with the defined query parameters instead of a body. For example, PUT https://host/apiv1/schema?attributeName=Some Test&dataType=Text&ownerId=q83dQm7rT9uKx1LzV5aP2g== would add the attribute Some Test, of data type Text, to the type Test, whose ID is 7, in the respective instance. The ID can be retrieved by first reading the schema data. Adding an attribute with the same name results in an error because the names are unique per type/relation. The same goes for attempting to create or delete attributes that have the reserved names of the aforementioned system attributes.