Table of Contents

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.

Query String

Output

A collection.

Permissions

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

HTTP status codes

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

Query String

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

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

Query String

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)):

• “email” users are identified by the e-mail provided and, if not, automatically generated (the user may specify a frontend_language for e-mail users)
• “collection” users are automatically generated using the secret provided: if the secret exists an error is returned

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

• the bag_write right for the collection, if it is an update (POST)
• the bag_acl right if any rights management attribute (*) is updated
• the bag_create right for the parent collection (PUT)
• if the collection is owned by the user, bag_write and bag_acl are not needed
• if the parent collection is owned by the user, bag_create is not needed

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

• rights management attributes (this requires the system.rights_management right)
• create_object attributes

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

HTTP status codes

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

Query String

Output

There is no output when the collection was removed successfully.

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

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

Query String

Output

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

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

Permissions

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

HTTP status codes

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

Query String

Input

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

Output

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

Permissions

The session must be authenticated and the user needs:

• the link right for the objects that are added to the collection (filtered by object type or pool)
• the unlink right for the objects that are removed from the collection (filtered by object type or pool)
• if the collection is owned by the user, link and unlink are not needed

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

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

Query String

Input

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

Output

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

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

Remove collection objects

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

Remove certain objects from a collection

Path parameters

Query String

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:

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

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

Query String

Input

An object with the following properties:

Output

An object with the following properties

Permissions

The session must be authenticated and the user needs:

• the link right for the objects that are added to the collection (filtered by object type or pool)
• the unlink right for the objects that are removed from the collection (filtered by object type or pool)
• if the collection is owned by the user, link and unlink are not needed

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

Example

// contents before splice
Request: GET /api/v1/collection/objects/1
Response: 200 OK
{
    "_version": 1,
    "offset": 0,
    "ccunt": 6,
    "objects": [
        <image-7>, <video-8>, <image-10>, <video-14>, <image-11>, <image-17>
    ]
}

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

// contents after splice
Request: GET /api/v1/collection/objects/1
Response: 200 OK
{
    "_version": 1,
    "offset": 0,
    "ccunt": 6,
    "objects": [
        <video-8>, <image-7>, <image-10>, <video-14>, <video-15>, <image-17>
    ]
}