Entity API

Owned by Pascal Hartmann (Unlicensed)
Last updated: Oct 30, 2019 by Claudius Knaak
10 min read

Overview

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


Create

ParameterTypeRequiredComment
actionString(tick)

create

see also API - General parameters

datasourceString
the url of the file to fetch
typeString or int(tick)
hridString

descriptionString

expirydatetimestamp
if set, the entity will be deleted after the expirydate
mimetypeString

only for type = 1 (File)

If not given, then the mime-type is extracted from the ending of the datasource

customdataJSON

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
pinboolean

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

parentuuid
uuid of the parent entity - if addreferences is also given, parent is ignored, see also Reference API
childuuid
uuid of the child entity - if addreferences is also given, child is ignored, see also Reference API
addreferencesJSON

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

removereferencesJSON
JSON with "children" = a list of child-uuids and "parents" = an array of parent-uuids to be removed, see also Reference API
refidString
the id of an external system
filesizelong

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!

checksumString

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 (question)


CreateBulk

ParameterTypeRequiredComment
actionString(tick)

createbulk

see also API - General parameters

entitiesJSONArray(tick)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 (question)

If a create-action for one entity does not work due to an exception, a rollback is done for the whole bulk action.


Delete


ParameterTypeRequiredComment
actionString(tick)

delete

see also API - General parameters

uuiduuid(tick)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 (question)


DeleteBulk

ParameterTypeRequiredComment
actionString(tick)

deletebulk

see also API - General parameters

entitiesJSONArray(tick)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 (question)

If a delete-action for one entity does not work due to an exception, a rollback is done for the whole bulk action.

Find

ParameterTypeRequiredComment
actionString(tick)

find

see also API - General parameters

fieldString(tick)

possible values:

  • description
  • hrid
  • refid
  • customdata
valueString(tick)the value that should be searched for
keyString
required only for search in customdata = the key in customdata to search for
offsetLong
set the offset
onlymultipleentriesBoolean
if set to true, the result will only contain entries with similiar descriptions - can only be used for description
ordercolumnsString
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"
}

(warning) 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 (question)



Info

ParameterTypeRequiredComment
actionString(tick)

info

see also API - General parameters

uuiduuid(tick)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
}

(warning) 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 (question)


Refinfo

ParameterTypeRequiredComment
actionString(tick)

refinfo

see also API - General parameters

uuiduuid(tick)see also API - General parameters
pocString
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 (question)


Update

ParameterTypeRequiredComment
actionString(tick)

update

see also API - General parameters

uuiduuid(tick)see also API - General parameters
descriptionString

pinboolean

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

expirydatetimestamp
if set the entity will be deleted after the expirydate
parentuuid
uuid of the parent entity - if addreferences is also given, parent is ignored, see also Reference API
childuuid
uuid of the child entity - if addreferences is also given, child is ignored, see also Reference API
addreferencesJSON

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

removereferencesJSON
JSON with "children" = a list of child-uuids and "parents" = an array of parent-uuids to be removed, see also Reference API
refidString
the id of an external system
filesizelong

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!

checksumString

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 (question)

UpdateBulk

ParameterTypeRequiredComment
actionString(tick)

updatebulk

see also API - General parameters

entitiesJSONArray(tick)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 (question)

If an update for one entity does not work due to an exception, a rollback is done for the whole bulk action.