2020.06

REST-API v2

Die REST-API kann vor allem durch externe Tools für den lesenden und schreibenden Zugriff auf MyCoRe-Objekte benutzt werden.

WORK_IN_PROGRESS: Es wurden noch nicht alle Endpoints der REST-API v2 vollständig beschrieben!

Allgemeines

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.

Dokumentation

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.

Zugriffsschutz

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.

Objekt-Metadaten verwalten

GET /objects

Dieser Request liefert eine Liste der vorhandenen MyCoRe-Objekte zurück.

Format

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.

Beispiel-Requests

GET /objects/{$id}

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:

 MCR.RestAPI.V2.AlternativeIdentifier.Objects.Keys=doi,issn,recordIdentifier

In der URL kann diese ID in der Form key:value verwendet werden.

Beispiel-Requests

 curl -o skeleton_simpledoc_00000036.xml
       http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000036

GET /objects/{$id}/metadata

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).

Beispiel-Requests

 curl -o metadata-for-skeleton_simpledoc_00000036.xml 
       http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000036/metadata

POST /objects

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.

Beispiel-Aufruf

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

PUT /objects/{$id}

aktualisiert die internen XML-Metadaten eines MyCoRe-Objektes.

Beispiel-Aufruf

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

PUT /objects/${id}/metadata

aktualisiert die <metadata>-Sektion eines MyCoRe-Objektes.

Beispiel-Aufruf

curl -D - -X PUT -u administrator:*PASSWORD*  
     -H "Content-Type: application/xml" 
     -d "@metadata-for-dskeleton_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

Derivate verwalten

GET /objects/{$id}/derivates

listet die Derivate eines MyCoRe-Objektes auf.

Parameter

{$id} analog zu /objects/{$id}

Format

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.

Beispiel-Requests

curl -H "Accept: application/json" 
     http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003/derivates

GET /objects/{$id}/derivates/{$derid}

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:

 MCR.RestAPI.V2.AlternativeIdentifier.Derivates.Keys=derivateType

In der URL kann diese ID in der Form key:value verwendet werden.

Beispiel-Requests

GET /objects/{$id}/derivates/{$derid}/contents/{$path}

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.

Format

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.

Beispiel-Requests

Hinweis: Datei-Downloads sind auch über die File-API realisierbar:

Beispiel-Requests

POST /objects/{$id}/derivates

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.

Parameter

`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`

Beispiel-Aufruf

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

PUT /objects/{$id}/derivates/${derid}/contents/${path}

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.

Beispiel-Aufruf

curl -D - -X PUT -u administrator:*PASSWORD*  
     -H "Content-Type: application/xml" 
     -d "@fulltext.pdf" 
     - http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000012/derivates/skeleton_derivate_00000032/contents/fulltext.pdf

Klassifikationen verwalten

GET /classifications

Dieser Request listet alle in der Anwendung installierten Klassifikationen auf.

Format

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.

Beispiel-Requests

GET /classifications/{$classid}

Anzeigen einer Klassifikation

Dieser Request zeigt eine Klassifikation aus der MyCoRe-Anwendung an.

{$classid} entspricht der ID einer Klassifikation

Format

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.