Table of Contents

Retrieve objects

GET /api/v1/db/<objecttype>/<mask>/<id>?token=<token>[&version=<version>[&schemaversion=<schemaversion>]][&format=<format>][&skip_reverse_nested=<skip_reverse_nested>]

Object by object ID (<objecttype>._id field). One object in the resulting array.

GET /api/v1/db/<objecttype>/<mask>/global_object_id/<id>?token=<token>[&version=<version>[&schemaversion=<schemaversion>]][&format=<format>][&skip_reverse_nested=<skip_reverse_nested>]

Object by global object ID (_global_object_id field): “local” is a valid alias for the server’s instance. One object in the resulting array.

GET /api/v1/db/<objecttype>/<mask>/system_object_id/<id>?token=<token>[&version=<version>[&schemaversion=<schemaversion>]][&format=<format>][&skip_reverse_nested=<skip_reverse_nested>]

Object by system object ID (_system_object_id field). One object in the resulting array.

GET /api/v1/db/<objecttype>/<mask>/list?token=<token>[&limit=<limit>][&offset=<offset>][&version=<version>[&schemaversion=<schemaversion>]][&format=<format>][&skip_reverse_nested=<skip_reverse_nested>]

List of objects, sorted ascending by object IDs (length of array controlled by parameters limit and offset). Multiple objects in the resulting array.

Path parameters

If the given mask does not exist in the schema for the given object version, an Old Mask Missing error is returned.

If no schema for the given object version is found, an Old Schema Missing error is returned.

Query String

Output

Array of objects in the requested format.

Permissions

The user needs the “read” right for the requested object and the “mask” right for the given mask (see rights management).

In order to use the “_all_fields” mask, the user needs any of the following system rights: “system.root”, “system.datamodel.development”, “system.datamodel.commit”.

HTTP status codes

Retrieve all versions of objects

GET /api/v1/db/<objecttype>/_all_fields/list?token=<token>&all_versions=true[&limit=<limit>][&offset=<offset>]

Returns all versions of all objects of this type, not filtered by any mask.

Path parameters

Query String

Output

Array of objects as above, ordered by object ID and version number. These differences to the single-version output exist:

• the newest version has a _latest_version marker set to true
• the comment given when creating the version is added as _comment
• there is a _last_modified timestamp for each version
• the ID of the user creating the version (creating or modifying the object) is present in _create_user
• the _owner field is simplified, no names but only ID of user or group is included (format and _basetype marker are kept compatible)
• _system_object_id_parent is added, containing the sytem object ID of the parent object
• there is no _path
• there is no changelog

Permissions

The system right system.root is required to use this request.

HTTP status codes

See single-version object retrieval for possible HTTP status codes.

Create or update objects

POST/PUT /api/v1/db/<objecttype>?token=<token>[&confirm=<confirm>][&collection=<collection_id>][&priority=<priority>][&format=<format>][&base_fields_only=1][&progress_uuid=<progress_uuid>]

Creates or updates objects for the given objecttype.

Objects are stored in the order of appearance. Each object must specify a _mask to be used for reading the object structure (see Object type). The _all_fields mask is accepted under certain conditions (see “Permissions”).

With every mask change, a batch is send to the Importer.

New objects must have either the creator or any of the groups they belong to as owner (except for the special case create in collection).

Group edit: It is possible to edit a group of objects in such a way that all of them are updated with the same data. In this mode, only one object is given in the input array, but the _id field is an array containing the IDs of the objects to be updated. The _version is automatically updated by the server.

Create in collection: If the parameter collection is provided, only insertions are allowed. The collection parameters define which objecttype, mask and pool are allowed for the objects (see collection). The objects will be created and inserted in the collection. The owner of the object will be the collection owner.

Base fields only: This is a special case in which no mask is provided. Only updates for pool and tags are allowed.

Notice: POST for masks with mask filters is not allowed.

Path parameters

Query String

Input

Array of objects. The following restrictions apply:

• _id must be set for POST and must be not set for PUT. It is an array in the group edit mode.
• _version must be 1 (PUT) or the current version plus one (POST).
• <object-type.name>._pool.pool.id can be set, but other properties of <object-type.name>._pool.pool are read-only.
• the rules for user-defined attributes depend on the object type and the _mask.
• other attributes are read-only.
• an object cannot be linked to the root pool, either on creation or update

_id and _id_parent can be set using a lookup feature, which selects the object using a reference column. More information about this feature can be found in the Lookups for IDs documentation.

Creation or regular update

The object is updated as a whole. That means that if the user only wants to change the value of a certain field, all other fields must be sent with their current values. Exceptions to this rule are:

• _acl - the user can leave the _acl as-is by not specifying it (no _acl entry) or setting it to null. To delete an _acl an empty array ([]) is needed
• _owner may be left out when creating an object

When creating an object, the owner must be the user that creates it. If _owner is left out, Easydb will fill this value. When using the collection parameter, the owner is automatically set to the owner of the collection.

Group edit

In group edit mode, only the given fields will be updated. Special instructions can be specified for lists:

Nested objects

If a nested field <field> is updated, the API expects a silbling string attribute <field>:group_mode, which can have the following values:

Tags

If the _tags are updated, the API expects a silbling string attribute _tags:group_mode, which can have the following values:

The mode tag_remove_all can be specified without _tags (if specified, they will be ignored).

ACL

If the _acl is updated, the API expects a silbling string attribute _acl:group_mode, which can have the following values:

The mode acl_remove_all can be specified without _acl (if specified, it will be ignored).

Output

If the request is a group edit or “base fields only”, the response body will be empty. Otherwise, it is an array of objects in the requested format.

Permissions

The user needs the following rights at the beginning of the operation (see rights management):

• “create”, if it is a new object
  • if collection was set, “create_in_collection” for the collection is required
• “write”, if it is an existing object
• “mask”, for the given mask
  • if collection was set, this is not required (the allowed mask is controlled via collection configuration)
• “acl”, if _acl is specified
• “change_owner”, if the _owner is changed (only when updating an object)
• if the user changes the pool of the object:
  • “link” for the new pool
  • “unlink” for the old pool

Transitions are checked (see transitions). If any transition needs confirmation, the call will return a confirmation response (see below “HTTP status codes”). The code provided in the confirmation response should be passed as parameter (confirm) when repeating the call.

If the transitions change the tags of the object, the rights are checked again. The user is not allowed to lose them at this point.

The user needs the following rights at the end of the operation:

• “mask”, for the given mask
• “read”
• “acl”, if _acl and/or _private_acl was specified

In order to use the “_all_fields” mask, the user needs any of the following system rights: “system.root”, “system.datamodel.development”, “system.datamodel.commit”.

If the parameter collection is set, the owner of the collection must have the rights granted by the collection to the created objects before they are inserted. Furthermore, they must be grantable. Otherwise, an error is returned.

The root pool is never allowed.

Example

[
    {
       "objekte": {
            "haupttitel": "Neuer Datensatz",
            "_version": 1,
            "_id_parent": null,
            "_pool": {
                "pool": {
                    "_id": 178
                }
            },
            "empfohlen": false
        },
        "_mask": "einzelmedien",
		"_tags": [
            {
                "_id": 26
            },
            {
                "_id": 13
            }
        ]
    }
]

HTTP status codes

Delete objects

DELETE /api/v1/db/<objecttype>?token=<token>[&confirm=<confirm>][&priority=<priority>]

Deletes one or more objects from the database.

Hierarchical objects: Deleting a hierarchical object automatically results in the deletion of all dependent objects.

Linked objects: Attempting to delete an object which is referenced from another object results in an error (HTTP code 409).

Path parameters

Query String

Input

An array of tuples (ID, version[, comment]). comment is optional and may be omitted.

[ [ 123, 4, “useless…” ], [ 124, 5, “replaced by ‘Test 3’” ], [ 126, 3 ] ]

Permissions

The user needs the “delete” right for the requested objects (see rights management).

Transitions are also checked (see transitions). If transitions need confirmation, the confirm parameter should be provided.

HTTP status codes