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