Entity API
Overview
Use the Entity API in order to manage IBS-Entities of different types.
Create
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String |  | create see also API - General parameters |
| datasource | String | the url of the file to fetch | |
| type | String or int | | |
| hrid | String | ||
| description | String | ||
| expirydate | timestamp | if set, the entity will be deleted after the expirydate | |
| mimetype | String | only for type = 1 (File) If not given, then the mime-type is extracted from the ending of the datasource | |
| customdata | JSON | possible entries:
| |
| pin | boolean | set this to true in order to pin the entity, i.e. create a self-referencing relation set this to false in order to unpin the entity, i.e. delete the self-referencing relation see Reference API | |
| parent | uuid | uuid of the parent entity - if addreferences is also given, parent is ignored, see also Reference API | |
| child | uuid | uuid of the child entity - if addreferences is also given, child is ignored, see also Reference API | |
| addreferences | JSON | JSON with "children" = a list of child-uuids and / or "parents" = an array of parent-uuids to be added, e.g. {"children" : ["428A57C1-B006-44AE-AAF3-7C72B3A28FE0" , "C879A548-7827-4628-ADF3-AE8A01C314F5"], "parents" : ["41C3CB6B-BC23-40BF-8582-790BDB904CA5", "0FF44487-C6D6-4960-A4D3-E67B73D897CF" ]}, see also Reference API | |
| removereferences | JSON | JSON with "children" = a list of child-uuids and "parents" = an array of parent-uuids to be removed, see also Reference API | |
| refid | String | the id of an external system | |
| filesize | long | the size in bytes of the file, given at datasource. If given, this value is used to check, whether the fetch succeeded correctly. FYI: The entity represents the logical file. Internally the fetched file is represented as a StorageEntity. The filesize of a StorageEntity may differ from the logical one, as we could implement a compression or encryption depending on the storage that is used. Therefore the values of this filesize and the one of the according StorageEntity may be different! | |
| checksum | String | the crc-checksum of the file, give at datasource. If given, this value is used to check, whether the fetch succeeded correctly. FYI: The entity represents the logical file. Internally the fetched file is represented as a StorageEntity. The checksum of a StorageEntity may differ from the logical one, as we could implement a compression or encryption depending on the storage that is used. Therefore the values of this checksum and the one of the according StorageEntity may be different! |
Example call
/api/v1/entities?action=create&type=1&datasource=http://example.org/image.png&description=Item1 POST /api/v1/entities type=1 datasource=http://example.org/image.png description=Item1
Answer
Success
{
"type": "Result:EntityApi:Create:Success",
"uuid": "149a8e27-9bb7-4dd3-9bba-f4913b113504"
}
Error
different error states 
CreateBulk
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | createbulk see also API - General parameters |
| entities | JSONArray | | a JSONArray containing the values for each entity that should be created. See create for possbile values. |
Example call
POST /api/v1/entities/createbulk
entities = [ { "type": 2, "description": "test 1" }, { "type": 3, "description": "test2" }, { "type":3, "description": "test3" } ]
Answer
Success
{
"entities": [
{
"type": "Success:EntityApi:Create",
"uuid": "20eb8cc6-57db-4568-b911-1d86976efe1d"
},
{
"type": "Success:EntityApi:Create",
"uuid": "1c33863f-da92-4c7f-87a5-b8102f730069"
},
{
"type": "Success:EntityApi:Create",
"uuid": "8380c211-0465-44d5-9fd1-553ae337c340"
}
],
"type": "Success:EntityApi:CreateBulk"
}
Error
different error states
If a create-action for one entity does not work due to an exception, a rollback is done for the whole bulk action.
Delete
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | delete see also API - General parameters |
| uuid | uuid | | see also API - General parameters |
Example call
/api/v1/entities?action=delete&uuid=149a8e27-9bb7-4dd3-9bba-f4913b113504 DELETE /api/v1/entities/149a8e27-9bb7-4dd3-9bba-f4913b113504
Answer
Success
{
"type": "Result:EntityApi:Delete:Success"
}
Error
different error states
DeleteBulk
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | deletebulk see also API - General parameters |
| entities | JSONArray | | a JSONArray containing the uuid for each entity that should be deleted. |
Example call 1
POST /api/v1/entities/deletebulk entities = [ "bc204f76-7f22-4c07-ad0f-cfb62f7b07fa", "f66ec4c3-258a-4a71-8238-4c7e439ba20a", "1e813623-c30a-4cf4-8347-8f4a1092bdcd" ]
Example call 2
POST /api/v1/entities/deletebulk
entities = [ { "uuid": "bc204f76-7f22-4c07-ad0f-cfb62f7b07fa"}, { "uuid": "f66ec4c3-258a-4a71-8238-4c7e439ba20a"}, { "uuid": "1e813623-c30a-4cf4-8347-8f4a1092bdcd"}]
Answer
Success
{
"entities": [
{
"type": "Success:EntityApi:Delete"
},
{
"type": "Success:EntityApi:Delete"
},
{
"type": "Success:EntityApi:Delete"
}
],
"type": "Success:EntityApi:DeleteBulk"
}
Error
different error states
If a delete-action for one entity does not work due to an exception, a rollback is done for the whole bulk action.
Find
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | find see also API - General parameters |
| field | String | | possible values:
|
| value | String | | the value that should be searched for |
| key | String | required only for search in customdata = the key in customdata to search for | |
| offset | Long | set the offset | |
| onlymultipleentries | Boolean | if set to true, the result will only contain entries with similiar descriptions - can only be used for description | |
| ordercolumns | String | one can set the order - if this string contains invalid columns, the standard sorting is used |
Example call
/api/v1/entity?action=find&field=refid&value="k342i5" POST /api/v1/entities action=find field=refid value="k342i5"
Answer
Success
{
"entities": [
{
"expirydate": "",
"creationdate": "2018-09-12 12:57:45",
"pinned": "false",
"downloadurl": "http://localhost:8084/api/api/v1/entities/4a2d501b-8981-4070-8f46-b6279f7a7e85/download",
"countparents": 1,
"modificationdate": "2018-09-13 09:45:21",
"uuid": "4a2d501b-8981-4070-8f46-b6279f7a7e85",
"entitytype": "FILE",
"hrid": "",
"datasource": "https://upload.wikimedia.org/wikipedia/commons/f/f1/Fairy_of_Eagle_Nebula.jpg",
"mimetype": "",
"state": "FETCHED",
"refid": "k342i5",
"countchildren": 0
}
],
"type": "Success:EntityApi:Find:refid"
}
Important:
- the downloadurl is only available, after the entity was sucessfully fetched.
- Please be aware, that the downloadurl can change - so you must not remeber it, but get the downloadurl by this or the Info-function right bevor downloading the file.
- Entites can only by downloaded by using the downloadurl
Error
different error states
Info
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | info see also API - General parameters |
| uuid | uuid | | see also API - General parameters |
Example call
/api/v1/entities?action=info&uuid=149a8e27-9bb7-4dd3-9bba-f4913b113504 GET /api/v1/entities/149a8e27-9bb7-4dd3-9bba-f4913b113504?action=info
Answer
Success
{
"creationdate": "2018-09-11 16:41:56",
"pinned": "true",
"datasource": "https://de.wikipedia.org/wiki/Pillars_of_Creation#/media/File:Eagle_nebula_pillars.jpg",
"downloadurl": "http://localhost:8084/api/api/v1/entities/d8779203-cac3-4a97-968a-e62ab59f304a",
"countparents": 1,
"mimetype": "image/jpeg",
"state": "FETCHED",
"refid": "custom57",
"type": "Success:EntityApi:Info",
"modificationdate": "2018-09-11 16:45:46",
"uuid": "d8779203-cac3-4a97-968a-e62ab59f304a",
"entitytype": "FILE",
"countchildren": 1
}
Important:
- the downloadurl is only available, after the entity was sucessfully fetched.
- Please be aware, that the downloadurl can change - so you must not remeber it, but get the downloadurl by this function right bevor downloading the file.
- Entites can only by downloaded by using the downloadurl
Error
different error states
Refinfo
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | refinfo see also API - General parameters |
| uuid | uuid | | see also API - General parameters |
| poc | String | set this to "parents" or leave blank to list children |
Example call
/api/v1/entities?action=refinfo&uuid=149a8e27-9bb7-4dd3-9bba-f4913b113504 GET /api/v1/entities/149a8e27-9bb7-4dd3-9bba-f4913b113504?action=refinfo
Answer
Success
{
"entitytype": "MANUFACTURER",
"children": [
{
"childtype": "PORTAL",
"childdescription": "ein portal",
"childuuid": "db1715f3-c59a-4bf7-8325-9b360d4f13d6",
"sub-child": [
{
"children": [
{
"childtype": "CUSTOMER",
"childdescription": "ein kunde",
"childuuid": "43016b9a-72cd-4209-89dd-4138c62b4cfc",
"sub-child": [
{
"children": [
{
"childtype": "PROJECT",
"childdescription": "ein Projekt",
"childuuid": "9ed80058-9006-4097-9bf5-17ea5fc00f6b",
"sub-child": [
{
"children": [
{
"childtype": "FILE",
"childdescription": " datei 1",
"childuuid": "d482a965-b547-467a-b267-53d610a6504d"
},
{
"childtype": "FILE",
"childdescription": "datei 2",
"childuuid": "4c8f8a4c-795c-47cd-adfa-fe3650e9d114"
},
{
"childtype": "FILE",
"childdescription": "datei 3",
"childuuid": "64ef025e-1fc6-44d7-9215-465b94691ddd"
}
]
}
]
}
]
}
]
}
]
}
]
}
],
"uuid": "cc5b64c0-6095-49b6-834b-8cf693023481"
}
Error
different error states
Update
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | update see also API - General parameters |
| uuid | uuid | | see also API - General parameters |
| description | String | ||
| pin | boolean | set this to true to pin the entity; only possible if state is NEW, SCHEDULED or FETCHED; set this to fals to un-pin the entity | |
| expirydate | timestamp | if set the entity will be deleted after the expirydate | |
| parent | uuid | uuid of the parent entity - if addreferences is also given, parent is ignored, see also Reference API | |
| child | uuid | uuid of the child entity - if addreferences is also given, child is ignored, see also Reference API | |
| addreferences | JSON | JSON with "children" = a list of child-uuids and / or "parents" = an array of parent-uuids to be added, e.g. {"children" : ["428A57C1-B006-44AE-AAF3-7C72B3A28FE0" , "C879A548-7827-4628-ADF3-AE8A01C314F5"], "parents" : ["41C3CB6B-BC23-40BF-8582-790BDB904CA5", "0FF44487-C6D6-4960-A4D3-E67B73D897CF" ]}, see also Reference API | |
| removereferences | JSON | JSON with "children" = a list of child-uuids and "parents" = an array of parent-uuids to be removed, see also Reference API | |
| refid | String | the id of an external system | |
| filesize | long | the size in bytes of the file, given at datasource. If given, this value is used to check, whether the fetch succeeded correctly. FYI: The entity represents the logical file. Internally the fetched file is represented as a StorageEntity. The filesize of a StorageEntity may differ from the logical one, as we could implement a compression or encryption depending on the storage that is used. Therefore the values of this filesize and the one of the according StorageEntity may be different! | |
| checksum | String | the crc-checksum of the file, give at datasource. If given, this value is used to check, whether the fetch succeeded correctly. FYI: The entity represents the logical file. Internally the fetched file is represented as a StorageEntity. The checksum of a StorageEntity may differ from the logical one, as we could implement a compression or encryption depending on the storage that is used. Therefore the values of this checksum and the one of the according StorageEntity may be different! |
Example call
/api/v1/entities?action=update&uuid=149a8e27-9bb7-4dd3-9bba-f4913b113504&description=Item1_tmp PATCH /api/v1/entities/149a8e27-9bb7-4dd3-9bba-f4913b113504 description=Item1_tmp
Answer
Success
{
"type": "Result:EntityApi:Update:Success"
}
Error
different error states
UpdateBulk
| Parameter | Type | Required | Comment |
|---|---|---|---|
| action | String | | updatebulk see also API - General parameters |
| entities | JSONArray | | a JSONArray containing the values for each entity that should be updated. See update for possbile values. |
Example call
POST /api/v1/entities/updatebulk
entities = [ { "uuid": "e5dfcdcd-2a26-47df-89d2-768ea4197ab8", "type": 1, "description": "test bulk update" }, { "uuid": "ea2b043c-4836-47f7-8258-ae3977eb945e", "type": 2, "description": "test2 bulk update" } ]
Answer
Success
{
"entities": [
{
"type": "Success:EntityApi:Update",
},
{
"type": "Success:EntityApi:Update",
},
{
"type": "Success:EntityApi:Update",
}
],
"type": "Success:EntityApi:UpdateBulk"
}
Error
different error states
If an update for one entity does not work due to an exception, a rollback is done for the whole bulk action.