DE EN EN (Google)

Retrieve collection

GET /api/v1/collection/<id>?token=<token>
GET /api/v1/collection/uuid/<uuid>?token=<token>

Retrieves information about a collection.

The system provides one top level Root-Collection which can be used to set top level rights. The top level Root-Collection is not included in searches and object output.

Path parameters

Depending on the call, the collection ID or UUID must be provided.

id Collection ID (integer)
uuid Collection UUID (text)

Query String

token Session token acquired with /api/v1/session

Output

A collection.

Permissions

The user must own the collection or have the bag_read right for it (see rights management).

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “bag_read” right
400 Collection Not Found: collection id not found
500 Server error: internal server error

Examples

Request:  GET /api/v1/collection/9
Response: HTTP 200
{
    "_basetype": "collection",
    "_count": 10,
    "_has_children": false,
    "collection": {
        "_id": 9,
        "_id_parent": 2,
        "_version": 2,
        "is_system_collection": false,
        "displayname": {
            "de-DE": "Hochzeit 2014",
            "en-US": "Wedding 2014"
        },
        "type": "presentation",
        "objects_unique": false,
        "children_allowed": false,
        "objects_allowed": true,
        "searchable": true,
        "webfrontend_props": {         // frontend-defined content; it must be an object
            "coords": [
                { "x": 0, "y": 0 },
                { "x": 190, "y": 230 }
            ]
        }
    }
}

Retrieve collections

GET /api/v1/collection/list[/<id_parent>]?token=<token>[&offset=<offset>][&limit=<limit>]

The collections build a hierarchy. This call returns all children of a given collection or, if the parent ID is set to null, the top level collections are returned.

If no parent ID is given, the hierarchy is ignored and all collections are returned, ordered by the collection ID.

Path parameters

id_parent Collection ID (integer or string null, optional) - if set to null, return the top level collections; if not set, return all collections without hierarchy
offset Index of the first object to be returned (integer, optional): defaults to 0
limit Maximum number of objects to be returned (integer, optional): defaults to 1000, maximum: 1000

Query String

token Session token acquired with /api/v1/session

Output

Array of collections (may be empty).

Permissions

The session must be authenticated. The list of collections returned are filtered as in the previous call (bag_read or owned by user).

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Collection Not Found: collection id_parent not found
400 User Not Found: user not found (in _acl.who or _owner.who)
400 Group Not Found: group not found (in _acl.who or _owner.who)
400 Tag Not Found: tag not found (in _acl.tagfilter)
500 Server error: internal server error

Example

Request:  GET /api/v1/collection/list
Response: HTTP 200
[
    {
        "_basetype": "collection",
        "_count": 0,
        "_has_children": true,
        "collection": {
            "_id": 1,
            "_version": 2,
            "displayname": {
                "de-DE": "Top level A",
                "en-US": "Top level A"
            },
            "type": "workfolder",
            "objects_unique": false,
            "children_allowed": true,
            "objects_allowed": false,
            "searchable": true
        }
    },
    {
        "_basetype": "collection",
        "_count": 2,
        "_has_children": true,
        "collection": {
            "_id": 2,
            "_version": 2,
            "displayname": {
                "de-DE": "Top level B",
                "en-US": "Top level B"
            },
            "type": "presentation",
            "objects_unique": false,
            "children_allowed": true,
            "objects_allowed": true,
            "searchable": true
        }
    }
]
Request:  GET /api/v1/collection/list/2
Response: HTTP 200
[
    {
        "_basetype": "collection",
        "_count": 10,
        "_has_children": false,
        "collection": {
            "_id": 9,
            "_id_parent": 2,
            "_version": 2,
            "displayname": {
                "de-DE": "Hochzeit 2014",
                "en-US": "Wedding 2014"
            },
            "type": "presentation",
            "objects_unique": false,
            "children_allowed": false,
            "objects_allowed": true,
            "searchable": true,
            "webfrontend_props": {
                "coords": [
                    { "x": 0, "y": 0 },
                    { "x": 190, "y": 230 }
                ]
            }
        }
    }
]

Create or update collection

PUT  /api/v1/collection?token=<token>
POST /api/v1/collection/<id>?token=<token>

Creates a new collection (PUT) or updates a collection (POST).

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session
collection_rights_policy What to do if the operation causes the owner of a collection to lose grantable rights over collection objects (see rightsmanagement)

Input

A collection.

Output

The collection that was created / updated.

Collection sharing

Collection sharing is accomplished by providing special “who” entries in the collection ACL (see user (short format)):

The collection ACL has a special attribute “send_email_notification” that can be used to send an e-mail when the ACL is updated.

Request:  POST /api/v1/collection
{
    "collection": {
        "_id": 9,
        "_version": 4
    },
    "_acl": [
        {
            "who": {
                "user": {
                    "type": "email",
                    "login": "john@example.com" // invite john@example.com to see and edit objects of this collection
                }
            },
            "rights": {
                "read": {},
                "write": {}
            },
            "send_email_notification": {
                "text": "Hey, John, look at this!" // also, send an e-mail to john@example.com
            }
        },
        {
            "who": {
                "user": {
                    "type": "collection",
                    "login": "c36c7bdd-877a-435e-bb29-77e70c26329a" // invite anonymous users to see objects of this collection
                }
            },
            "rights": {
                "read": {}
            }
        },
        { "who": { "user":  { "_id": 25 } }, "rights": { "read": {} } }, // other normal ACL entries
        { "who": { "group": { "_id":  7 } }, "rights": { "read": {} } }
    ]
}
Response: HTTP 200
{
    "_acl": [
        {
            "who": {
                "user": {
                    "_id": 76, // the user now exists in the system and has an ID
                    "type": "email", // the user type is "email"
                    "login": "john@example.com",
                    "_generated_displayname": "john@example.com"
                }
            },
            "rights": {
                "read": {},
                "write": {}
            }
        },
        {
            "who": {
                "user": {
                    "_id": 77, // the user now exists in the system and has an ID
                    "type": "collection", // the user type is "collection"
                    "login": "c36c7bdd-877a-435e-bb29-77e70c26329a",
                    "_generated_displayname": "c36c7bdd-877a-435e-bb29-77e70c26329a"
                }
            },
            "rights": {
                "read": {}
            }
        },
        ...
    ],
    ...
}

Permissions

The user must own the collection or have the bag_read right for it

System collections cannot be created, but they can be updated. Only the following parameters are allowed to be modified:

(*) The following attributes are in the rights management group: _acl, _private_acl.

HTTP status codes

200 Success
202 Confirmation Response (collection owner rights revoked): the operation requires confirmation with a collection_rights_policy
400 API error: something is malformed
400 Collection Name Repeated: a collection with the same name exists under the same parent collection
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “bag_write” right
400 No System Right: user lacks the required system right to update the collection
400 Collection Does Not Allow Children: trying to create or move a collection under a collection that does not allow children
400 System Collection Update: trying to change an attribute of a system collection which cannot be changed
400 Collection Not Found: collection id or collection._id_parent not found (the error tells which one)
400 Tag Not Found: a tag that was provided for a tag filter in the collection _acl was not found
400 Right Not Found: a right that was provided in the _acl was not found
400 Collection Requires Parent: a new collection (PUT) requires a parent
400 Collection Is Not Under User Collection: the collection is not under the user collection
400 Collection User Secret Already Exists: the secret already exists
500 Server error: internal server error

Examples

Request:  PUT /api/v1/collection
{
    "collection": {
        "_version": 1,
        "displayname": {
            "de-DE": "Neue Arbeitsmappe",
            "en-US": "New workfolder"
        },
        "_id_parent": 2,
        "type": "workfolder"
    }
}
Response: HTTP 200
{
    "_basetype": "collection",
    "_count": 0,
    "_has_children": false,
    "collection": {
        "_id": 34,               // ID is returned in the response
        "_version": 1,
        "displayname": {
            "de-DE": "Neue Arbeitsmappe",
            "en-US": "New workfolder"
        },
        "_id_parent": 2,
        "objects_unique": false,
        "children_allowed": false,
        "objects_allowed": false,
        "searchable": false
    }
}
Request:  POST /api/v1/collection
{
    "collection": {
        "_id": 9,
        "_version": 3,
        "displayname": {
            "de-DE": "Hochzeit 2013",
            "en-US": "Wedding 2013"
        }
    }
}
Response: HTTP 200
{
    "_basetype": "collection",
    "_count": 10,
    "_has_children": false,
    "collection": {
        "_id": 9,
        "_id_parent": 2,
        "_version": 2,
        "displayname": {
            "de-DE": "Hochzeit 2013",
            "en-US": "Wedding 2013"
        },
        "type": "presentation",
        "objects_unique": false,
        "children_allowed": false,
        "objects_allowed": true,
        "searchable": true,
        "webfrontend_props": {
            "coords": [
                { "x": 0, "y": 0 },
                { "x": 190, "y": 230 }
            ]
        }
    }
}

Remove collection

DELETE /api/v1/collection/<id>?token=<token>

Removes a collection.

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session

Output

The collection that was removed.

Permissions

The user must own the collection or have the bag_delete right for it (see rights management).

System collections are not allowed to be deleted.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “bag_read” right
400 Collection Not Found: collection id not found
400 System Collection Delete: operation not allowed because collection id is a system collection
500 Server error: internal server error

Examples

Request:  DELETE /api/v1/collection/9
Response: HTTP 200

Retrieve objects from a collection

GET /api/v1/collection/objects/<id>?token=<token>[&offset=<offset>][&limit=<limit>]

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session
offset Index of the first object to be returned (integer): defaults to 0
limit Maximum number of objects to be returned (integer): defaults to 1000, maximum: 1000

Output

The output is given as a map with the following parameters:

_version Collection version (integer)
offset Given offset (integer)
limit Given limit (integer or null)
count Total number of objects in the collection (integer)
objects Array of “collection objects”

The order of the objects in a collection is important. A “collection object” has the following attributes:

_global_object_id Global Object ID (string): ref object._global_object_id
_webfrontend_props Custom data (object, nullable): frontend-defined properties

Permissions

The user must own the collection or have the bag_read right for it (see rights management).

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “bag_read” right
400 Collection Not Found: collection id not found
500 Server error: internal server error

Examples

Request:  GET /api/v1/collection/objects/7?offset=2
Response: HTTP 200
{
    "_version": 4,
    "offset": 2,
    "limit": null,
    "count": 5,                                     // collection 7 has 5 elements
    "objects": [                                    // elements [2,3,4]
        {
            "_global_object_id": "5@easydb-demo",
            "_webfrontend_props": null              // custom data may be null, but it is always present
        },
        {
            "_global_object_id": "2@easydb-demo",
            "_webfrontend_props": {                 // custom data can contain anything, but it has to be an object
                "alignment": "top",
                "color": "red"
            }
        },
        {
            "_global_object_id": "1236@some-other-easydb",    // objects can be stored in remote Easydbs
            "_webfrontend_props": null
        }
    ]
}

Update collection objects

POST /api/v1/collection/objects/<id>?token=<token>

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session

Input

The input is given as a map with the following parameters:

objects Array of “collection objects”

Output

The output is given as a map with the following parameters:

_version Collection version (integer)
count Number of objects in the collection (integer)

Permissions

The session must be authenticated and the user needs:

New objects are granted some rights through the collection ACL. The owner of the collection must have these rights over the objects before the operation. Furhtermore, they must be grantable.

See rights management.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “link” or “unlink” right
400 No Grantable Right: the owner of the collection has no grantable right for the new objects
400 Collection Not Found: collection id not found
400 Object Not Found: object not found, the global object id is given as parameter of the error
500 Server error: internal server error

Examples

Request:  POST /api/v1/collection/objects/7
[
    {
        "_global_object_id": "1236@some-other-easydb",
        "_webfrontend_props": null
    },
    {
        "_global_object_id": "5@easydb-demo",
        "_webfrontend_props": null
    },
    {
        "_global_object_id": "2@easydb-demo",
        "_webfrontend_props": {
            "alignment": "top",
            "color": "red"
        }
    },
    {
        "_global_object_id": "87349@easydb-demo",
        "_webfrontend_props": {
            "alignment": "center",
            "color": "black"
        }
    }
]
Response: HTTP 200
{
    "_version": 4,
    "count": 4
}

Insert objects to a collection

POST /api/v1/collection/push/<id>

This call appends objects to the end of the collection. It works the same way as the previous call, but extending the list, rather than replacing it.

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session

Input

The input is given as a map with the following parameters:

objects Array of “collection objects”

Output

The output is given as a map with the following parameters:

_version Collection version (integer)
count Number of objects in the collection (integer)

Permissions

The session must be authenticated and the user must own the collection of have the link right for the objects that are added to it (filtered by object type or pool).

New objects are granted some rights through the collection ACL. The owner of the collection must have these rights over the objects before the operation. Furhtermore, they must be grantable.

See rights management.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “link” right
400 No Grantable Right: the owner of the collection has no grantable right for the new objects
400 Collection Not Found: collection id not found
400 Object Not Found: object not found, the global object id is given as parameter of the error
500 Server error: internal server error

Remove collection objects

POST /api/v1/collection/remove/<id>

Remove certain objects from a collection

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session

Input

An array of “collection objects”. _webfrontend_props is not used in this case.

Output

The output is given as a map with the following parameters:

_version Collection version (integer)
count Number of objects in the collection (integer)

Permissions

The session must be authenticated and the user must own the collection of have the link right for the objects that are added to it (filtered by object type or pool).

New objects are granted some rights through the collection ACL. The owner of the collection must have these rights over the objects before the operation. Furhtermore, they must be grantable.

See rights management.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “link” right
400 No Grantable Right: the owner of the collection has no grantable right for the new objects
400 Collection Not Found: collection id not found
400 Object Not Found: object not found, the global object id is given as parameter of the error
500 Server error: internal server error

Splice collection objects

POST /api/v1/collection/splice/<id>

Perform a splice operation with the collection objects.

A splice operation removes a given range of objects, and appends a given set of objects to the collection. The range can be specified by giving a starting index and a count of objects to be removed.

If no index is specified, no objects will be removed before new objects are appended. If count is not set, all objects from the start index are removed.

If index and count are not specified, no objects are removed.

Handling of existing objects

If any of the new collection objects in objects are already in the collection, they will be moved from their current position in the collection to a new position at the end, according to the sorting of the appended objects.

Path parameters

id Collection ID (integer)

Query String

token Session token acquired with /api/v1/session

Input

An object with the following properties:

index Start position to remove items (integer, defaults to size of collection)
count Number of items to be removed (integer, defaults to all elements from start to end)
objects Items to be added (array of “collection objects”, defaults to an empty array)

Output

An object with the following properties

_version Collection version (integer)
count Number of elements in the collection (integer)
objects Removed items (array of strings): instead of “collection objects”, this is a list of global object IDs

Permissions

The session must be authenticated and the user needs:

New objects are granted some rights through the collection ACL. The owner of the collection must have these rights over the objects before the operation. Furhtermore, they must be grantable.

See rights management.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no “link” or “unlink” right
400 No Grantable Right: the owner of the collection has no grantable right for the new objects
400 Collection Not Found: collection id not found
400 Object Not Found: object not found, the global object id is given as parameter of the error
500 Server error: internal server error

Example

Request: GET /api/v1/collection/objects/1
Response: 200 OK
[ image-7, video-8, image-10, video-14, image-11, image-17 ]

Request: POST /api/v1/collection/splice/1
{ "index": 3, "count": 2, "objects": [ image-7, image-10, video-14, video-15 ] }
Response: 200 OK
{ "objects": [ video-14, image-11 ], "count": 6 }

Request: GET /api/v1/collection/objects/1
Response: 200 OK
[ video-8, image-7, image-10, video-14, video-15, image-17 ] // 6 elements