Programming interface (REST API)

The old TUdatalib REST interface is no longer available.

With the upgrade of TUdatalib in June 2025, the previous REST interface will no longer be available. Software that was connected to TUdatalib via this interface must be converted to the new interface.

Scope

This guideline is primarily intended for users of TU Darmstadt. Partner universities that also use this system may have different rules. Find more about those here: Contact

1 Using TUdatalib via the REST interface

The REST interface allows you to create datasets and add files and metadata to them without using the graphical user interface (web interface) of TUdatalib.

The functions of the DSpace 8 REST interface are described in detail in the corresponding documentation. We prepared sample scripts and code fragments here that illustrate how to interact with this interface for the Python 3 programming language. For Python 3, there is an open source library called DSpace REST Client that simplifies accessing this interface for many applications.

1.1 Required permissions

You do not usually need administrative rights for the collection in which you want to create a dataset. However, you do need administrative rights to change the metadata of an existing dataset.

Administrator rights are also required if you want to add files and metadata to a record that has already been archived (i.e., one that has completed the workflow). Otherwise, publication rights are sufficient to add files and metadata to a record that has not yet been completed.

1.2 Installing the Python Requests Library

To install the Requests library on your system, you need pip3. To do this, open the command line (terminal) and execute the following commands:

*   pip install requests
*   pip install dspace-rest-client

The following modules are also required to execute the scripts, but are normally part of the standard Python library.

*   pip install getpass
*   pip install logging
*   pip install json
*   pip install argparse

1.3 Download the sample scripts for Python

We provide sample scripts for creating data sets and uploading files and metadata to existing data sets, which can be executed independently if Python and requests are installed correctly. These are available for free use here: TUdatalib REST Examples.

1.4 Using the sample scripts for Python

Download the directory and unzip it to any location. The exported directory contains the following files and folders:

The files create_item.py and update_metadata.py are the scripts you need to run when you want to create a dataset or add metadata to a dataset. These scripts access information in corresponding configuration files located in the 'configs' folder.

To ensure that the scripts work properly, you should fill in the configuration files before executing the scripts. Each script has its own configuration file:

For example, create_item.py accesses config_create_item.py to obtain the information necessary for creating the dataset. Please also note the information in the 'README.md' file.

The 'sf' folder contains files necessary for the scripts to function, and nothing in it should be edited by the user! Above all, do not delete the __init__.py files in the folders (if present). These are also necessary for the scripts to function, even if they are empty.

1.5 Filling in the configuration files

Before executing the scripts in the main folder, you should fill in the corresponding configuration file in the 'configs' subfolder.

1.5.1 Contents of config_create_item.py for creating datasets

The following information is required to create datasets in the TUdatalib data archive:

Internal ID of the collection in which you want to create a dataset
- This can be found in the URL of each collection under: https://tudatalib.ulb.tu-darmstadt.de/collections/{your collection ID}
- Only the sequence of numbers after '/collections/' is relevant here.
Metadata such as the name of the record, author, or date of submission
- An empty template is available in the config_create_item.py file.

Enter the ID of the collection as a Python string, i.e. in quotation marks.

The metadata of a dataset consists of a list (Python list) of metadata entries. Each metadata entry is a Python dictionary that has at least the entries key, value, and language. The entries under key determine which metadata field (of the Dublin Core schema) is involved. The entry under value determines the respective value of the field. If a language specification is not applicable, None can be entered under language.

An example is shown in the image. Further information can be found in the file itself or below.

collection_id = "xxx" # Please enter the ID of the collection to which you want to add an item here.

metadata = [
    {
        "key": "dc.title",
        "value": "Test example",
        "language": "en",
        "authority": None,
        "confidence": -1,
        "place": 0
    },
    {
        "key": "dc.contributor.author",
        "value": "Mustermann, Max",
        "language": None,
        "authority": None,
        "confidence": -1,
        "place": 0
    },
    {
        ...
    }
]

The following metadata is required for the successful submission and archiving of a data set: dc.title, dc.contributor.author, dc.description, dc.type, dc.date.created, dc.subject.classification, dc.rights.license, tuda.agreements.

By setting the value of tuda.agreememts to true, you accept the usage agreements of TUDA for the corresponding dataset.

By setting the value of tuda.agreememts to true, you accept the terms of use of TUdatalib in their current version for the corresponding dataset. datasets for which the terms of use are not accepted during upload will be rejected by the system.

Field name	Repeatable	Description / Permitted values
Authors	Yes	Multiple authors can be specified.
Relations	Yes	Relationships to other objects (e.g., related publication, dataset, etc.).
Type	Yes	See permitted values for `dc.type` below.
Subject Keywords	Yes	Free keywords describing the content.
DFG subject	Yes	Must correspond to the following format: `"value": "1.11-01"` (DFG classification).
Third-party funded project	Yes	Information on projects funded by third parties.

Permitted values for `dc.type`:

Description (English)	Configuration value (`"value"`)
Pure data set (database, tables, etc.)	`Dataset`
Text	`Text`
Software (code and/or binaries)	`Software`
Image data	`Image`
Audio data	`Sound`
Audiovisual data (e.g., video)	`Audiovisual`
Interactive resource	`Interactive Resource`
Model	`Model`
Workflow	`Workflow`
Other	`Other`

Example for dc.type:

{
    "key": "dc.type",
    "value": "Text",
    "language": "en",
    "authority": null,
    "confidence": -1,
    "place": 0
}

Format for dc.subject.classification:

{
  "key": "dc.subject.classification",
  "value": "1.11-01", // Example value
  "language": null,
  "authority": null,
  "confidence": -1,
  "place": 0
}

All permissible values for the DFG classification can be found here.

Permitted values for `dc.rights` (licenses):

Description	Configuration value (`"value"`)	Link to license
CC0 1.0 - Public Domain Dedication	`CC0-1.0`	https://creativecommons.org/publicdomain/zero/1.0/
CC BY 4.0 - Attribution 4.0 International	`CC-BY-4.0`	https://creativecommons.org/licenses/by/4.0/
CC BY-NC 4.0 - Attribution-NonCommercial 4.0 International	`CC-BY-NC-4.0`	https://creativecommons.org/licenses/by-nc/4.0
Open Data Commons Attribution License (ODC-By) v1.0	`ODC-BY-1.0`	https://opendatacommons.org/licenses/by/1.0/
Open Data Commons Open Database License (ODbL) v1.0	`ODbL-1.0`	https://opendatacommons.org/licenses/odbl/1.0/
Open Data Commons Public Domain Dedication and License (PDDL) v1.0	`PDDL-1.0`	https://opendatacommons.org/licenses/pddl/1.0/
Open Data Commons Database Contents License (DbCL) v1.0	`DbCL-1.0`	https://opendatacommons.org/licenses/dbcl/1.0/
MIT License	`MIT`	https://opensource.org/licenses/MIT
3-Clause BSD License (NewBSD)	`BSD-3-Clause`	https://opensource.org/licenses/BSD-3-Clause
2-Clause BSD License (FreeBSD)	`BSD-2-Clause`	https://opensource.org/licenses/BSD-2-Clause
GPL - GNU General Public License 3.0	`GPL`	https://www.gnu.org/licenses/gpl-3.0.en.html
LGPL - GNU Lesser General Public License 3.0	`LGPL`	https://www.gnu.org/licenses/lgpl-3.0.en.html
Apache License 2.0	`Apache-2.0`	https://www.apache.org/licenses/LICENSE-2.0
No license (not recommended)	`InC`	https://rightsstatements.org/vocab/InC/1.0/
Other license (please specify name and URL)	`other`	-

Example for dc.license

    {
        "key": "dc.rights.license",
        "value": "CC0-1.0",
        "language": null,
        "authority": null,
        "confidence": -1,
        "place": 0
    }

Notice regarding the file upload

If you want to add files to a dataset, the following information is required:

Path to the file or the folder of the files to be uploaded

If using folder paths, please note that the entire content of the specified folder is always added to the data set. Therefore, if necessary, create a new folder with files that are to be added to a data set. In addition, always specify the entire path to the folder, not just part of it. Please note that at least one correct list element must exist in upload_path in order to execute the script.

An example of an upload list could look like this: Further information can be found in the file itself or below.

upload_path = [
 "C:/Users/User/SampleFolder1",
 "C:/Users/User/SampleFolder2"
 ]

1.5.3 Contents of config_update_metadata.py for adding metadata

If you want to add metadata to an existing dataset, the following information is required:

Internal ID of the dataset
List of metadata entries (one per dataset ID)

Further information can be found in the file itself or below. An example excerpt of the metadata could look like this:

metadata = [
    {
        "key": "dc.title",
        "value": "Sample item",
        "language": "en",
        "authority": None,
        "confidence": -1,
        "place": 0
    },
    {
        "key": "dc.contributor.author",
        "value": "Mustermann, Max",
        "language": None,
        "authority": None,
        "confidence": -1,
        "place": 0
    },
    {
        "key": "dc.type",
        "value": "Text",
        "language": None,
        "authority": None,
        "confidence": -1,
        "place": 0
    },
]

1.5.4 How do I obtain the ID of a collection?

To find out the ID of a collection, you can navigate to the target collection and read the ID directly from the URL: * This can be found in the URL of each collection under: https://tudatalib.ulb.tu-darmstadt.de/collections/{your collection ID} * Only the sequence of numbers after /collections/ is relevant here.

1.5.5 How do I obtain the ID of a dataset?

To find the ID of a dataset, navigate to the target dataset and read the ID directly from the URL: * This can be found in the URL of each collection under: https://tudatalib.ulb.tu-darmstadt.de/collections/{your collection ID} * Only the sequence of numbers after /collections/ is relevant here.

If you want to edit a workspace item that has not yet been published, you can read the item ID from the URL that leads to the respective item as follows: https://tudatalib.ulb.tu-darmstadt.de/workspaceitems/{your item ID}/view * Only the sequence of numbers between /workspaceitems/ and /view is relevant here.

1.6 Overview of individual functions

The following section provides an overview of the functions and the associated parameters:

Class: DSpaceItemCreator

init(api_endpoint=None, email=None, password=None, client=None)

Initializes the class with API endpoint and access data or an existing DSpaceClient.

Parameters: api_endpoint (str): URL of the DSpace REST API email (str): User email password (str): User password client (DSpaceClient): Optional, already authenticated client

login(email: str, password: str) -> None

Manually logs in to the REST API.

Parameters: email (str): User email password (str): User password

create_item(collection_id: str, metadata: list[dict], upload_path: str = None, cleanup_on_fail: bool = False) -> None

Creates a DSpace item and adds metadata and files.

Parameters: collection_id (str): Target collection ID metadata (list[dict]): List of metadata entries (e.g., {"key": "dc.title", "value": "Title"}) upload_path (str, optional): Path to the file to be uploaded or list of paths cleanup_on_fail (bool, optional): Deletes the workspace item in case of error

_discard_workspace_item(item_id: int)

Deletes a created workspace item on error.

Parameters: item_id (int): ID of the item to be deleted

_prepare_patch_data(metadata: list[dict]) -> list[dict]

Formats the metadata for a PATCH request to DSpace.

Parameters: metadata (list[dict]): List of metadata

Return: list[dict]: Formatted PATCH data structure

External dependencies (important modules & configs)

dspace_rest_client.client.DSpaceClient: DSpace REST API client class for authentication and session handling

configs.config_create_item.collection_id: ID of the target collection for the new item

configs.config_create_item.metadata: List of metadata for the item

configs.config_create_item.upload_path: List or path(s) for file(s) to be uploaded