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 bag_write right for the pools to be updated
the bag_acl right if any rights management attribute (*) is updated, for pools other than the root pool
the system.rights_management right if any rights management attribute (*) is updated, for the root pool
the bag_create right for the parent pools of the pools to be created

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