DE EN EN (Google)

Retrieve pools

GET /api/v1/pool[/<id>]?token=<token>

Get one or all pools.

The system provides one top level Root-Pool which can be used to set top level transitions, tags and right. The top level Root-Pool is not included in searches and object output.

Path parameters

id Pool ID (integer, optional): if set, get pool id

Query String

token Session token acquired with /api/v1/session

Output

Array of pools (full format).

Whether information about the ACL (fields _acl and _private_acl) of the pool is included in the output depends on the right of the user. If the user has the bag_write right, the ACL information is included. If the user only has the bag_read right, this information is not included.

Permissions

The session must be authenticated and the user needs the bag_write or bag_read right for the pool(s) (see rights management).

Notice that if an id was provided and the pool is not readable this API call returns a 400 error, but if no id is provided, the non-readable pools are filtered out. This call may return an empty array.

HTTP status codes

200 Success
400 API error: something is malformed
400 Not Authenticated: session is not authenticated
400 Insufficient Rights: no bag_write right
400 Pool Not Found: pool id not found
500 Server error: internal server error

Examples

Request:  GET /api/v1/pool
Response: HTTP 200
[
    {
        "_basetype": "pool",
        "pool": {
            "_id": 2,
            ...
        },
        ...
    },
    {
        "_basetype": "pool",
        "pool": {
            "_id": 9,
            ...
        },
        ...
    },
    ...
]
Request:  GET /api/v1/pool/9
Response: HTTP 200
[
    {
        "_basetype": "pool",
        "pool": {
            "_id": 9,
            ...
        },
        ...
    }
]

Insert or update pools

PUT/POST /api/v1/pool?token=<token>

Creates or updates a set of pools.

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

Array of pools (full format).

Output

Array of pools (full format) that were inserted / updated.

Permissions

The session must be authenticated and the user needs:

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

HTTP status codes

200 Success
400 API error: something is malformed
202 Confirmation Response (collection owner rights revoked: the operation requires confirmation with a collection_rights_policy
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 pool
400 System Pool Update Parent: trying to change the parent of a system pool
400 Pool Not Found: pool id or pool._id_parent not found (the error tells which one)
400 User Not Found: user not found (in _acl.who, _transitions.who or contact)
400 Group Not Found: group not found (in _acl.who or _transitions.who)
400 Tag Not Found: tag not found (in _tags or _acl.tagfilter)
400 Pool Requires Parent: a new pool (PUT) requires a parent
500 Server error: internal server error

Examples

Request:  PUT /api/v1/pool
[
    {
        "pool": {
            "_id_parent": 9,
            "_version": 1,
            "name": {
                "de-DE": "Altertum",
                "en-US": "Antique"
            }
        }
    }
]
Response: HTTP 200
[
    {
        "pool": {
            "_id": 3,               // ID is returned in the response
            "_id_parent": 9,
            "_version": 1,
            "name": {
                "de-DE": "Altertum",
                "en-US": "Antique"
            },
            ...
        },
        ...
    }
]
Request:  POST /api/v1/pool
[
    {
        "pool": {
            "_id": 3,
            "_version": 2,            // client increases the version
            "watermark": {
                "dissolve": 50,
                "gravity": "ne",
                "size": "50%x50%",
                "tile": true,
                "image": {
                    "id": 1000095450
                }
            }
        }
    }
]
Response: HTTP 200
[
    {
        "pool": {
            "_id": 3,                  // fields that are not provided, like "_id_parent" and "name" remain untouched
            "_id_parent": 9,
            "_version": 2,
            "name": {
                "de-DE": "Altertum",
                "en-US": "Antique"
            },
            "watermark": {
                "dissolve": 50,
                "gravity": "ne",
                "size": "50%x50%",
                "tile": true,
                "image": {
                    "id": 1000095450,
                    ...
                }
            },
            ...
        },
        ...
    }
]

Delete pool

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

Delete a pool. In order to delete a pool, it must be empty. That means that it cannot contain other pools, but also that there are no objects in it.

Path parameters

id Pool ID (integer)

Query String

token Session token acquired with /api/v1/session

Examples

Request:  DELETE /api/v1/pool/3
Response: HTTP 200

Permissions

The session must be authenticated and the user needs the bag_delete right for the pool (see rights management).

System pools 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_delete” right
400 Pool Not Found: pool id not found
400 System Pool Delete: pool id is a system pool
500 Server error: internal server error