Preface
Qbilon provides a deletion API that allows you to precisely delete asset data from Qbilon. The deletion API can delete data from Qbilon using explicit IDs, targeting either entire assets or only specific properties of assets. For this purpose, the data endpoint/apiv1/data/delete/{taskId} allows POST requests to be received.
To use the deletion endpoint, two conditions must be met:
- a prepared data source (see section REST API) in whose name deletion requests are sent to Qbilon (this is the
{taskId}part in the URL), and - compliance with the data format as defined in Qbilon’s OpenAPI specification (navigate to
Documentation → API Documentationor enter the URL<myhost>/openapi/index.html).
Data Format
The Qbilon Deletion API supports complete and partial deletion of assets and relations in your Qbilon instance. It uses a simple format in JSON that can be included in the body of a POST request to delete data from Qbilon. The body consists of some optional parts and some mandatory parts. This allows a user to delete exactly as much information as desired.Full-Fledged Deletion Format
A full-fledged example of the format for a body deleting different assets/relations either fully or partially from Qbilon could look like this:Deleting an Asset/Relation
For each asset that you want to delete, you first have to provide information about whether it is an asset or a relation. This is done by providing the corresponding ID in either thetypeElements or relationElements array. For each asset to be deleted, you have to provide an object in the array consisting of either an externalId , i.e., an ID that was used within the data source given in the URL, or a global qbilonId. If both are given, the qbilonId takes precedence, with no fallback to the externalId if the qbilonId is not found.
In order to delete the whole asset or relation, the object provided in the array must not have a properties field, but only externalId and/or qbilonId, as shown in the following example.
If you delete an asset that has incoming or outgoing relations, those relations are implicitly deleted as well, since there can be no relations without a corresponding source or target asset in Qbilon.
Deleting an Asset/Relation Property
In order to delete only one or more properties of an asset or relation, you can provide the optionalproperties array. Within this array you can provide the names of the properties that should be deleted. If this field is provided, the asset/relation will not be deleted, only the given properties. If none of the given properties are found in the given asset/relation, nothing will happen.
Deletion Response
Qbilon provides you with a detailed response about what happened during the deletion of the provided assets, relations or their properties. A valid response for the above deletion request could look like this:- If you successfully deleted a single asset, the response would look like this:
- If you successfully deleted a single asset and the property of another asset, the response would look like this:
- If you successfully deleted a property of one asset, but failed to do the same on another asset (as it doesn’t exist):
- If you successfully deleted one property of an asset, but failed to delete another because it didn’t exist, and another because it was a system property:
Error Handling
Format Violations
There are cases that are not handled gracefully by Qbilon, but result in an endpoint call error:Inconsistent Input
Qbilon will always try to delete as much as possible from your given request, but if something went wrong during deleting an asset/relation or its properties, the response will contain the optionalerrors array.
Within this array, there will be explanations for each whole asset/relation and also its properties as to why the deletion couldn’t be performed as requested.
The following cases are handled in a graceful manner:
