Zum Inhalt

Programmierschnittstelle (REST-API)

Die alte TUdatalib REST Schnittstelle ist nicht mehr länger verfügbar.

Mit dem Upgrade von TUdatalib im Juni 2025 ist die vorherige REST Schnittstelle nicht länger verfügbar. Software, die über diese an TUdatalib angebunden war, muss auf die neue Schnittstelle umgestellt werden.

Scope

Dieser Leitfaden ist in erster Linie für Nutzende der TU Darmstadt gedacht. Partnerhochschulen, die das System auch nutzen, haben ggf. andere Regeln. Siehe auch Kontakt

1 Nutzung von TUdatalib mittels REST-Schnittstelle

Mit der REST-Schnittstelle gibt es eine Möglichkeit, wie Sie Datensätze erstellen, sowie Dateien und Metadaten zu diesen hinzufügen können, ohne die grafische Oberfläche (Webinterface) von TUdatalib zu verwenden.

Die Funktionen der DSpace 8 REST Schnittstelle sind im Detail in der entsprechenden Dokumentation dargestellt. Wir stellen Ihnen Beispielskripte und Codefragmente zur Verfügung, die die Interaktion mit dieser Schnittstelle für die Programmiersprache Python 3 veranschaulichen. Diese finden Sie hier.

Für Python 3 existiert mit dem DSpace REST Client eine Open Source Bibliothek, die das Ansprechen dieser Schnittstelle für viele Anwendungen vereinfacht.

1.1 Erforderliche Berechtigungen

Sie benötigen in der Regel keine Administrationsrechte für die Sammlung, in der Sie einen Datensatz erstellen wollen. Zur Änderung der Metadaten eines bestehenden Datensatzes brauchen Sie allerdings Administrationsrechte.

Ebenso werden Administrator-Rechte benötigt, wenn Sie Dateien und Metadaten zu einem bereits archivierten Datensatz (also einem, der den Workflow vollständig durchlaufen hat) hinzufügen wollen, ansonsten ist die Veröffentlichungsberechtigung ausreichend um Dateien und Metadaten zu einem noch nicht abgeschlossenen Datensatz hinzuzufügen.

1.2 Installation der Python-Requests-Library

Um die Requests-Library auf Ihrem System zu installieren, wird pip3 benötigt. Öffnen Sie dazu die Kommandozeile (Terminal) und führen Sie die folgenden Befehle aus:

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

Die folgenden Module werden ebenfalls zur Ausführung der Skripte benötigt, sind allerdings im Normalfall Teil der Standardbibliothek von Python.

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

1.3 Download der Beispiel-Skripte für Python

Wir stellen für das Erstellen von Datensätzen sowie zum Hochladen von Dateien und Metadaten zu bestehenden Datensätzen Beispiel-Skripte zur Verfügung, die bei ordnungsgemäßer Installation von Python und requests eigenständig ausführbar sind. Diese finden Sie zur freien Verwendung hier: TUdatalib REST Examples.

1.4 Benutzung der Beispiel-Skripte für Python

Laden Sie das Verzeichnis herunter und entpacken Sie es an einem beliebigen Ort. Das exportierte Verzeichnis enthält folgende Dateien und Ordner:

Die Dateien create_item.py und update_metadata.py sind die von Ihnen auszuführenden Skripte, wenn Sie einen Datensatz erstellen, Dateien in einen Datensatz hochladen oder Metadaten zu einem Datensatz hinzufügen wollen. Diese Skripte greifen auf Informationen in entsprechenden Konfigurationsdateien zu, die sich im Ordner 'configs' befinden.

Damit die Skripte ordnungsgemäß funktionieren, sollten Sie die Konfigurationsdateien ausfüllen, bevor Sie die Skripte ausführen. Jedes Skript hat eine eigene Konfigurationsdatei:

So greift z.B. create_item.py auf config_create_item.py zu, um für die Datensatzerstellung notwendige Informationen zu erhalten. Beachten Sie auch die Hinweise in der 'README.md'-Datei.

Der Ordner 'sf' enthält für die Funktion der Skripte notwendige Dateien und nichts darin sollte vom Benutzer bearbeitet werden! Löschen Sie vor allem nicht die __init__.py in den Ordnern (falls vorhanden). Diese sind ebenfalls für die Funktion der Skripte notwendig, auch wenn sie leer sind.

1.5 Ausfüllen der Konfigurationsdateien

Vor dem Ausführen der Skripte im Hauptordner sollten Sie die entsprechende Konfigurationsdatei im Unterordner 'configs' ausfüllen.

1.5.1 Inhalt der config_create_item.py zum Erstellen von Datensätzen

Zum Erstellen von Datensätzen im Datenarchiv TUdatalib werden folgende Informationen benötigt:

  • Interne ID der Sammlung in der Sie einen Datensatz erstellen wollen
    • Diese findet sich in der URL einer jeden Collection unter: https://tudatalib.ulb.tu-darmstadt.de/collections/{ihre Collection-ID}
    • Hier ist nur die Zahlenfolge hinter '/collections/' relevant.
  • Metadaten wie z.B. Name des Datensatzes, Autor oder Datum der Einreichung
    • Eine unausgefüllte Vorlage liegt in der config_create_item.py-Datei vor.

Geben Sie die ID der Sammlung als Python-String an, d.h. in Anführungszeichen.

Die Metadaten eines Datensatzes bestehen aus einer Liste (Python-Liste) von Metadateneinträgen. Jeder Metadateneintrag ist ein Python-Dictionary das mindestens die Einträge key, value und language hat. Die Einträge unter key legen fest, um welches Metadatenfeld (des Dublin Core Schemas) es sich handelt. Der Eintrag unter value legt den jeweiligen Wert des Feldes fest. Unter language lässt sich, wenn eine Sprachangabe nicht anwendbar ist, None eintragen.

Im Bild ist ein Beispiel gegeben. Weitere Informationen finden Sie in der Datei selbst oder weiter unten.

collection_id = "xxx" # Geben Sie bitte hier die ID zu der Sammlung ein, der Sie ein Item hinzufügen wollen.

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

Zur erfolgreichen Einreichung und Archivierung eines Datensatzes bedarf es der folgenden Metadaten: dc.title, dc.contributor.author, dc.description, dc.type, dc.date.created, dc.subject.classification, dc.rights.license, tuda.agreements.

Mit dem setzen des Wertes von tuda.agreememts auf true akzeptieren Sie für den entsprechenden Datensatz die Nutzungsvereinbarungen von TUdatalib in der jeweils aktuellen Version. Datensätze, bei denen beim Hochladen die Nutzungsbedingungen nicht akzeptiert werden, werden vom System abgelehnt.

Feldname Wiederholbar Beschreibung / Erlaubte Werte
Beteiligte Personen Ja Mehrere Autor:innen können angegeben werden.
Verknüpfte Ressourcen Ja Beziehungen zu anderen Objekten (z. B. zugehörige Publikation, Dataset, etc.).
Typen Ja Siehe zulässige Werte für dc.type unten.
Schlagworte Ja Freie Schlagworte zur inhaltlichen Beschreibung.
DFG-Fach Ja Muss folgendem Format entsprechen: "value": "1.11-01" (DFG-Klassifikation).
Drittmittelprojekt Ja Informationen zu drittmittelgeförderten Projekten.

Zulässige Werte für dc.type:

Beschreibung Konfigurationswert ("value")
Reines Datenset (Datenbank, Tabellen o. ä.) Dataset
Text Text
Software (Code und/oder Binaries) Software
Bilddaten Image
Audiodaten Sound
Audiovisuelle Daten (z. B. Video) Audiovisual
Interaktive Ressource Interactive Resource
Modell Model
Workflow Workflow
Anderes Other

Beispiel für dc.type: 

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

Format für dc.subject.classification:

{
  "key": "dc.subject.classification",
  "value": "1.11-01", // Beispielwert
  "language": null,
  "authority": null,
  "confidence": -1,
  "place": 0
}
Alle zulässigen Werte der DFG-Klassifizierung finden sie hier

Zulässige Werte für dc.rights (Lizenzen):

Beschreibung (Deutsch) Konfigurationswert ("value") Link zur Lizenz
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
Keine Lizenz (nicht empfohlen) InC https://rightsstatements.org/vocab/InC/1.0/
Andere Lizenz (Bitte Namen und URL angeben) other -

Beispiel für dc.license

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

Hinweise bezüglich des Dateiuploads Wenn Sie Dateien zu einem Datensatz hinzufügen möchten, werden folgende Informationen benötigt:

  • Pfad zur Datei oder zum Ordner mit den Dateien, die hochgeladen werden sollen

Bei Angabe von Ordnern: Bitte beachten Sie, dass immer der gesamte Inhalt des angegebenen Ordners zu dem Datensatz hinzugefügt wird. Erstellen Sie daher gegebenenfalls einen neuen Ordner mit Dateien, die zu einem Datensatz hinzugefügt werden sollen. Geben Sie außerdem immer den gesamten Pfad zu dem Ordner an, nicht nur einen Teil davon. Bitte beachten Sie, dass zur Ausführung des Skripts mindestens ein korrektes Listenelement in upload_path bestehen muss.

Ein Beispiel für eine Uploadliste könnte wie folgt aussehen: Weitere Informationen finden Sie in der Datei selbst oder weiter unten.

upload_path = [
               "C:/Users/User/Beispielordner1",
               "C:/Users/User/Beispielordner2"
              ]

1.5.3 Inhalt der config_update_metadata.py zum Hinzufügen von Metadaten

Wenn Sie Metadaten zu einem bestehendem Datensatz hinzufügen möchten, werden die folgenden Informationen benötigt:

  • Interne ID des Datensatzes
  • Liste von Metadateneinträgen (eine pro Datensatz ID)

Weitere Informationen finden Sie in der Datei selbst order weiter unten. Ein Beispiel-Ausschnitt für die Metadaten könnte wie folgt aussehen: 

metadata = [
    {
        "key": "dc.title",
        "value": "Beispielitem",
        "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 Wie erhalte ich die ID einer Sammlung?

Um die ID einer Sammlung herauszufinden, können Sie in die Zielsammlung navigieren und dort die ID direkt aus der URL auslesen: * Diese findet sich in der URL einer jeden Collection unter: https://tudatalib.ulb.tu-darmstadt.de/collections/{ihre Collection-ID} * Hier ist nur die Zahlenfolge hinter /collections/ relevant.

1.5.5 Wie erhalte ich die ID eines Datensatzes?

Um die ID eines Datensatzes herauszufinden, navigieren Sie zu dem Zieldatensatz und lesen Sie dort die ID direkt aus der URL aus: * Diese findet sich in der URL einer jeden Collection unter: https://tudatalib.ulb.tu-darmstadt.de/collections/{ihre Collection-ID} * Hier ist nur die Zahlenfolge hinter /collections/ relevant.

Wollen Sie ein Workspace-Item bearbeiten, welches noch nicht veröffentlicht ist, dann können Sie die Item-ID aus der URL die zum jeweiligen Item führt wie folgt auslesen: https://tudatalib.ulb.tu-darmstadt.de/workspaceitems/{ihre Item-ID}/view * Hierbei ist nur die Zahlenfolge zwischen /workspaceitems/ und /view relevant.

1.6 Übersicht der einzelnen Funktionen

Der folgende Abschnitt bietet eine Übersicht der Funktionen und der zugehörigen Parameter:

Klasse: DSpaceItemCreator

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

Initialisiert die Klasse mit API-Endpunkt und Zugangsdaten oder einem bestehenden DSpaceClient.

Parameter:

`api_endpoint (str)`: URL der DSpace-REST-API

`email (str)`: Benutzer-E-Mail

`password (str)`: Benutzer-Passwort

`client (DSpaceClient)`: Optional, bereits authentifizierter Client

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

Meldet sich manuell bei der REST-API an.

Parameter:

`email (str)`: Benutzer-E-Mail

`password (str)`: Benutzer-Passwort

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

Erstellt ein DSpace-Item und fügt Metadaten sowie Dateien hinzu.

Parameter:

`collection_id (str)`: Ziel-Collection-ID

`metadata (list[dict])`: Liste der Metadateneinträge (z. B. {"key": "dc.title", "value": "Titel"})

`upload_path (str, optional)`: Pfad zur hochzuladenden Datei oder Liste von Pfaden

`cleanup_on_fail (bool, optional)`: Löscht das Workspace-Item bei Fehler

_discard_workspace_item(item_id: int)

Löscht ein erstelltes Workspace-Item bei Fehlern.

Parameter:

`item_id (int)`: ID des zu löschenden Items

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

Formatiert die Metadaten für einen PATCH-Request an DSpace.

Parameter:

`metadata (list[dict])`: Liste der Metadaten

Rückgabe:

`list[dict]`: Formatierte PATCH-Datenstruktur

Externe Abhängigkeiten (wichtige Module & Configs)

dspace_rest_client.client.DSpaceClient: DSpace REST API Client-Klasse für Authentifizierung und Session-Handling

configs.config_create_item.collection_id: ID der Ziel-Collection für das neue Item

configs.config_create_item.metadata: Liste der Metadaten für das Item

configs.config_create_item.upload_path: Liste oder Pfad(e) für hochzuladende Datei(en)