Entity API

Overview

Use the Entity API in order to manage IBS-Entities of different types.

1 Overview
2 Create
- 2.1 Example call
- 2.2 Answer
  - 2.2.1 Success
  - 2.2.2 Error
3 CreateBulk
- 3.1 Example call
- 3.2 Answer
  - 3.2.1 Success
  - 3.2.2 Error
4 Delete
- 4.1 Example call
- 4.2 Answer
  - 4.2.1 Success
  - 4.2.2 Error
5 DeleteBulk
- 5.1 Example call 1
- 5.2 Example call 2
- 5.3 Answer
  - 5.3.1 Success
  - 5.3.2 Error
6 Find
- 6.1 Example call
- 6.2 Answer
  - 6.2.1 Success
  - 6.2.2 Error
7 Info
- 7.1 Example call
- 7.2 Answer
  - 7.2.1 Success
  - 7.2.2 Error
8 Refinfo
- 8.1 Example call
- 8.2 Answer
  - 8.2.1 Success
  - 8.2.2 Error
9 Update
- 9.1 Example call
- 9.2 Answer
  - 9.2.1 Success
  - 9.2.2 Error
10 UpdateBulk
- 10.1 Example call
- 10.2 Answer
  - 10.2.1 Success
  - 10.2.2 Error

Create

Parameter	Type	Required	Comment

Parameter	Type	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: de.jenomics.ikona.binarystore.worker.schedule.StandardScheduleProcessor.fetchcount: int value = number of downloads. The first one is downloaded and the other ones are copied from the download de.jenomics.ikona.binarystore.worker.schedule.StandardScheduleProcessor.fetchduedate: timestamp, sets the time when a download can start de.jenomics.ikona.binarystore.worker.schedule.StandardScheduleProcessor.copyduedate: timestamp, sets the time when a download should be copied - only if downloads > 1 de.jenomics.ikona.binarystore.worker.schedule.StandardScheduleProcessor.fetchstorage: uuid of the storage that should be used for download de.jenomics.ikona.binarystore.worker.schedule.StandardScheduleProcessor.copystorage: uuid of the storage that should be used for copying - only if downloads > 1 filesize: if given, the filesize is compared to this value after fetching checksum: the crc-checksum in hex-format. If given, the crc-checksum of the file after download is compared to this one
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

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

Parameter

Type

Required

Comment

action

String

delete

see also API - General parameters

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

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

Parameter	Type	Comment
action	String	find see also API - General parameters
field	String	possible values: description hrid refid customdata
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

Parameter

Type

Required

Comment

action

String

info

see also API - General parameters

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

Parameter

Type

Required

Comment

action

String

refinfo

see also API - General parameters

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

Parameter	Type	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

Parameter	Type	Required	Comment
action