Die REST-API kann vor allem durch externe Tools für den lesenden und schreibenden Zugriff auf MyCoRe-Objekte benutzt werden.
Mit dem LTS 2020.06 wurde die MyCoRe-REST-API überarbeitet.
Neben dem lesenden Zugriff besteht jetzt auch die Möglichkeit Objekte zu erstellen, bearbeiten und zu löschen.
Die Basis-URL der neuen REST-API lautet: ${WebApplicationBaseURL}api/v2
.
Neben der Beschreibung auf dieser Webseite, liefert jede MyCoRe-Anwendung auch eine Dokumentation der REST-Schnittstelle im OpenAPI-Format aus: z.B.: http://mycore.de/mir/api/v2/openapi.json.
Die Nutzung der REST-API wird durch ACLs geschützt.
Für den lesenden Zugriff muss immer eine ACL auf restapi:/
mit dem Recht read
gesetzt sein.
Der Zugriff auf einzelne Pfade wie /objects
, /search
oder
/classifications
kann durch entsprechende ACLs (z.B. restapi:/v2/objects
)
zusätzlich beschränkt werden.
Für den schreibenden Zugriff muss eine eine ACL auf restapi:/
mit dem Recht writedb
gesetzt sein.
Durch Setzen entsprechender ACL-Regeln kann der Zugriff komplett freigeschaltet (TRUE
),
auf einzelne Nutzer oder Rollen beschränkt oder auf bestimmte IP-Adressen / IP-Bereiche begrenzt werden.
Dieser Request liefert eine Liste der vorhandenen MyCoRe-Objekte zurück.
Die Liste kann im XML-Format (default) oder JSON-Format zurückgeliefert werden.
Das Format kann entweder via HTTP-Header (Accept: application/json
bzw. Accept: application/xml
)
oder via URL-Endung (/objects.json
bzw. /objects.xml
) definiert werden.
Dieser Request liefert die internen XML-Metadaten eines MyCoRe-Objektes zurück.
{$id} |
entspricht im Standardfall der MyCoRe-Objekt-ID. Führende Nullen werden ggf. automatisch ergänzt. Anstelle der ID können alternative Identifier verwenden werden. Voraussetzung dafür ist, dass sie als SOLR-Feld definiert wurden, dass genau ein Dokument zurückliefert. Über das Property MCR.RestAPI.V2.AlternativeIdentifier.Objects.Keys kann eine Liste von Feldern angegeben werden:
key:value verwendet werden.
|
curl -o skeleton_simpledoc_00000036.xml
http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000036
Dieser Request liefert die <metadata>
-Sektion eines MyCoRe-Objektes zurück.
{$id} |
entspricht im Standardfall der MyCoRe-Objekt-ID. Führende Nullen werden ggf. automatisch ergänzt. Anstelle der ID können alternative Identifier verwenden werden (s. oben). |
curl -o metadata-for-skeleton_simpledoc_00000036.xml
http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000036/metadata
erstellt ein neues MyCoRe-Objekt.
Im Request-Body muss ein valides MyCoRe-Objekt mitgeliefert werden.
Aus der MyCoRe-ID werden Projekt und Objekttyp übernommen, der Zählerbestandteil wird vom System mit dem aktuellen Wert überschrieben.
Der Response enthält einen Location
-Header mit der URL des neuen MyCoRe-Objektes.
curl -D -X POST -u administrator:*PASSWORD*
-H "Content-Type: application/xml"
-d "@skeleton_simpledoc_00000001.xml"
- http://localhost:8080/skeleton/api/v2/objects
<mycoreobject ID="skeleton_simpledoc_00000001">
<structure />
<metadata>
<def.title class="MCRMetaLangText" heritable="false" notinherit="true">
<title inherited="0" form="plain">Meine erste Publikation</title>
</def.title>
<def.language class="MCRMetaClassification" heritable="false" notinherit="true">
<language inherited="0" classid="rfc4646" categid="en"/>
</def.language>
</metadata>
<service>
<servstates class="MCRMetaClassification">
<servstate inherited="0" classid="state" categid="submitted"/>
</servstates>
</service>
</mycoreobject>
Daten für Upload: MyCoRe-Objekt als XML in Datei skeleton_simpledoc_00000001.xml
aktualisiert die internen XML-Metadaten eines MyCoRe-Objektes.
curl -D - -X PUT -u administrator:*PASSWORD*
-H "Content-Type: application/xml"
-d "@skeleton_simpledoc_00000036.xml"
http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000036
aktualisiert die <metadata>
-Sektion eines MyCoRe-Objektes.
curl -D - -X PUT -u administrator:*PASSWORD*
-H "Content-Type: application/xml"
-d "@metadata-for-skeleton_simpledoc_00000001.xml"
http://localhost:8080/skeleton/api/v2/objects/metadata
<metadata>
<def.title class="MCRMetaLangText" heritable="false" notinherit="true">
<title inherited="0" form="plain">Meine aktualisierte Publikation</title>
</def.title>
<def.language class="MCRMetaClassification" heritable="false" notinherit="true">
<language inherited="0" classid="rfc4646" categid="en"/>
</def.language>
</metadata>
Daten für Upload: Metadaten als XML-Datei metata-for-skeleton_simpledoc_00000001.xml
listet die Derivate eines MyCoRe-Objektes auf.
{$id} |
analog zu /objects/{$id} |
Die Liste kann im XML-Format (default) oder JSON-Format zurückgeliefert werden.
Das Format kann entweder via HTTP-Header (Accept: application/json
bzw. Accept: application/xml
)
oder via URL-Endung (/derivates.json
bzw. /derivates.xml
) definiert werden.
curl -H "Accept: application/json"
http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003/derivates
Dieser Request liefert das interne XML eines MyCoRe-Derivates zurück
{$id} |
analog zu /objects/{$id} |
{$derid} |
entspricht im Standardfall der MyCoRe-Derivate-ID. Führende Nullen werden ggf. automatisch ergänzt. Anstelle der ID können alternative Identifier verwenden werden. Voraussetzung dafür ist, dass sie als SOLR-Feld definiert wurden, dass genau ein Dokument zurückliefert. Über das Property MCR.RestAPI.V2.AlternativeIdentifier.Derivates.Keys kann eine Liste von Feldern angegeben werden:
key:value verwendet werden.
|
Mit diesem Request erhält man ein Directory-Listing für im Derivate enthaltene Ordner oder lädt die spezifizierte Datei herunter.
{$id} |
analog zu /objects/{$id} |
{$derid} |
analog zu /objects/{$id}/derivates/{$derid} |
{$path} |
optional: Pfad zu einem Verzeichnis im Derivate, dessen Inhalt hier ausgegeben werden soll bzw. zu einer Datei die heruntergeladen werden soll. |
Die Liste kann im XML-Format (default) oder JSON-Format zurückgeliefert werden.
Das Format kann entweder via HTTP-Header (Accept: application/json
bzw. Accept: application/xml
)
oder via URL-Endung (/contents.json
bzw. /contents.xml
) definiert werden.
Hinweis: Datei-Downloads sind auch über die File-API realisierbar:
erstellt ein neues MyCoRe-Derivate.
Die initialen Metadaten werden als Form-Parameter übergeben.
Der Response enthält einen Location
-Header mit der URL des neuen MyCoRe-Objektes.
order |
Reihenfolge (Position) des Derivates in den MyCoRe-Metadaten |
maindoc |
Pfad zur Hauptdatei im Derivate |
classification |
(wiederholbar) Klassifikationseinträge für das Derivate in der Form classid:categid |
title |
(wiederholbar) Title des Derivates, die Sprache kann dem Text in runden Klammern vorangestellt werden, z.B.
(en)published article |
curl -D -X POST -u administrator:*PASSWORD*
-H "Content-Type: application/x-www-form-urlencoded"
-F "order=1"
-F "title=(de)Volltextdokument"
-F "title=(en)fulltext document"
-F "classification=derivate_types:content"
- http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000012/derivates
lädt eine neue Datei hoch bzw. aktualisiert eine existierende Datei.
Der Response hat den Statuscode 201
, wenn eine neue Datei erstellt wurde
oder den Statuscode 204
, wenn eine bestehende Datei aktualisiert wurde.
curl -D - -X PUT -u administrator:*PASSWORD*
-H "Content-Type: application/pdf"
-d "@fulltext.pdf"
- http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000012/derivates/skeleton_derivate_00000032/contents/fulltext.pdf
Dieser Request listet alle in der Anwendung installierten Klassifikationen auf.
Die Liste kann im XML-Format (default) oder JSON-Format zurückgeliefert werden.
Das Format kann entweder via HTTP-Header (Accept: application/json
bzw. Accept: application/xml
)
oder via URL-Endung (/classifications.xml
bzw. /classifications.json
) definiert werden.
Dieser Request zeigt eine Klassifikation aus der MyCoRe-Anwendung an.
{$classid} | entspricht der ID einer Klassifikation |
Die Liste kann im XML-Format (default) oder JSON-Format zurückgeliefert werden.
Das Format kann entweder via HTTP-Header (Accept: application/json
bzw. Accept: application/xml
)
oder via URL-Endung (/{$classid}.json
bzw. /{$classid}.xml
) definiert werden.