API
Coscine verfügt über eine Programmierschnittstelle, mit der sich Arbeitsabläufe automatisieren lassen.
Coscine REST API
Mit Coscine kann über eine REST Schnittstelle (REpresentational State Transfer) interagiert werden. Dazu benötigen Sie zunächst ein Zugriffstoken, welches Sie in Ihrem Benutzerprofil anlegen können (siehe Zugriffstoken erstellen). Um sich mit den einzelnen Funktionen und deren Benutzung vertraut zu machen, sollten Sie einen Blick in die API Dokumentationsseite werfen. Dort können Sie die Funktionen auch mit eigenen Parametern testen.
API Dokumentation
Die Coscine REST API wurde mittels Swagger entworfen und dokumentiert. Auf der eigens dafür eingerichteten API Dokumentationsseite finden Sie Informationen zu den API Endpunkten und können die API direkt live mittels eines API-Tokens austesten. Alternativ gibt es eine zweite interaktive Dokumentationsseite, mit der Sie für konkrete Endpoints ausführbare Beispiele in verschiedenen Programmiersprachen erzeugen können.
Coscine API Swagger Dokumentation Interaktive Coscine API Dokumentation
Wichtige Informationen
Rate limiting
Coscine beschränkt die API requests pro Minute auf 500. Das heißt innerhalb
einer Minute dürfen Sie nicht mehr als 500 requests machen. Wird dieser
Schwellenwert überschritten, kann es dazu kommen, dass Ihre Anfragen
für einige Zeit von Coscine ignoriert werden. Sinn und Zweck des ganzen
ist die Vermeidung einer Überlastung der Coscine Server - sei es eine
unbewusste oder eine gezielte mit bösen Absichten hervorgerufene Überlastung.
Entwickler, die eine sequentielle Anbindung an die API benutzen, werden
den Schwellenwert sehr wahrscheinlich nicht überschreiten. Sollten Sie
allerdings bestimmte Abläufe parallelisieren oder asynchrone Anfragen
versenden, sollten Sie sich vorher Gedanken machen, wie Sie unter
500 Anfragen pro Minute bleiben können.
Es schadet nicht vorab eine kleine Rechnung anzustellen, mittels der Sie
eine grobe Schätzung hinsichtlich der durchschnittlichen API Nutzung
erhalten können. Dazu wählen Sie einfach eine variable round trip time (RTT)
und multiplizieren diese mit der Anzahl requests X, die Sie parallel oder
asynchron versenden können bzw. maximal erreichen werden. Falls Sie z.B. einen
ThreadPool nutzen, entspräche dies der Anzahl der verwendeten threads.
Dauert es durchschnittlich 0.5 Sekunden bis Ihre Anfrage Coscine erreicht
und Sie eine Antwort erhalten, können Sie X Anfragen pro 0.5 Sekunden
versenden. Ist nun z.B. ihr X=8 und RTT=0.5s, können Sie 8*(1/0.5s) = 16
Anfragen pro Sekunde versenden. Multiplizieren Sie dies mit 60 Sekunden, so
erhalten Sie die erwarteten Anfragen pro Minute (unter optimalen Bedingungen) -
in unserem Rechenbeispiel wären das also 960 Anfragen pro Minute, womit wir
die erlaubten 500 pro Minute um fast das doppelte überschritten haben.
Page Size
Einige API-Endpoints arbeiten mit großen Mengen an Daten. Damit nicht all
diese Daten auf einmal in einer großen response versendet werden müssen,
teilt Coscine große Datenmengen in viele kleinere (pages) auf und indiziert
diese jeweil mit einem Index. Sie können die Größe dieser pages, d.h. die
Anzahl der Elemente die sie enthalten selbst festlegen, allerdings ist die
maximale Anzahl der Elemente pro page auf 50 limitiert. Darüber hinaus
können Sie einzelne pages über ihren Index anfordern. Wichtig dabei ist,
dass sich der Index abhängig von der gewählten Anzahl der Elemente ändert.
Auch die Anzahl der pages ändert sich dabei.
Um alle Daten eines paginierten Endpoints zu erhalten, müssen Sie alle pages
anfordern und die Resultate am Ende zusammenfügen.
File Actions
Coscine bietet für Dateien in Ressourcen sogenannte presigned-URLs an, mit denen
Nutzer direkten Zugriff auf Dateien erhalten, ohne sich vorher mittels eines
API-Tokens legitimieren zu müssen. Diese URLs sind für einen Zeitraum von
24 Stunden gültig und verfallen nach Ablauf dieser Zeitspanne.
Um die Gültigkeit aufrecht zu erhalten, müssen die URLs über ein neues request
neu angefordert werden. Coscine erstellt die URLs automatisch serverseitig.
Nutzung der API
Nutzung eines bestehenden API-Clients
Die Coscine REST API können Sie mit einer Vielzahl an Programmiersprachen nutzen. Eine Client-Bibliothek in der Programmiersprache Python wird derzeit aktiv von der Coscine Nutzerbase gepflegt:
Coscine Python SDK Coscine Python SDK Dokumentation
Kontaktieren Sie uns gerne, wenn Sie ein Script oder eine Bibliothek zur Interaktion mit Coscine geschrieben haben, und dies auch anderen Nutzern zugänglich machen möchten. Coscine und dessen Nutzer profitieren als Open-Source Projekt direkt von Beiträgen der Community. Gemeinsam lässt sich mehr erreichen - zögern Sie daher nicht Ihre Arbeit auch nach außen zu tragen, sofern Ihnen dadurch kein Nachteil entsteht.
Entwicklung eines eigenen API-Clients
Mithilfe von Swagger können API Clients erstellt werden, mit denen Sie die Coscine API in einer Vielzahl von Programmiersprachen nutzen können. Hierfür muss die Swagger Spezifikation zur API heruntergeladen, die gewünschte Programmiersprache (z.B. Python) ausgewählt werden und anschließend können die entsprechenden Clients erstellt werden. Dadurch können eigene API Anwendungen erstellt und an die individuellen Bedürfnisse angepasst werden, z.B. wenn Community Projekte wie das Coscine Python SDK sich für die eigenen Anforderungen nicht passend herausstellen. Weiterführende Informationen finden Sie in der Dokumentation des Swagger-Projekts.
Automatisch generierte API Clients Coscine API Swagger Spezifikation
Unterstützung bei der technischen Adaption
Innerhalb der Coscine Community hat sich die Coscine Technical Adaption Group (CTA)
formiert, die Forscherinnen und Forscher bei der technischen Adoption von Coscine
unterstützt. Konkret werden Skripte, Programme, Best Practices und Beratungsangebote
an Nutzer kommuniziert. Um ein möglichst breites Angebot an Unterstützung anbieten
zu können ist die Mitarbeit von Nutzern erwünscht. So sind Community-Projekte, die auch
für andere Forschende von Interesse wären, immer gern gesehen und werden daher auch gerne
mit in das Angebot mit aufgenommen und an Nutzer kommuniziert.
Die CTA Gruppe steht in ständigem Austausch mit Nutzern von Coscine und dem Coscine
Entwicklerteam selbst und ist somit immer über neueste Entwicklungen oder feature
requests im Bilde.
Weitere Informationen finden Sie auf der Landing Page der CTA Gruppe:
Dort finden Sie auch eine Möglichkeit, mit Mitgliedern der Gruppe in Kontakt zu treten.