2020.06 2021.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.

Mit dem LTS 2021.06 wurden Zugriffsschlüssel in mycore-acl eingeführt. Zugriffsschlüssel können grundsätzlich nur im JSON-Format verwaltet werden.

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

REST-API Endpoints

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-skeleton_simpledoc_00000001.xml" 
     http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_000000001/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

Verwaltung von Zugriffsschlüsseln auf Objekte

Die Zugriffsschlüssel werden im JSON-Format definiert.
2021.06 mycore-acl

GET /objects/{$id}/accesskeys?offset={$offset}&limit={$limit}

Dieser Request liefert eine Liste aller Zugriffsschlüssel eines MyCoRe-Objekts zurück.

{$id} analog zu /objects/{$id}
{$offset} optional: Legt das Offset der Liste der zuletzt verwalteten Zugriffsschlüssel fest. Default: 0.
{$limit} optional: Legt die Größe der Liste der zuletzt verwalteten Zugriffsschlüssel fest. Default: 128.
Format

Die Liste wird im JSON-Format zurückgeliefert.

2021.06 mycore-acl

GET /objects/{$id}/accesskeys/{$secret}?secret_encoding={$secret_encoding}

Dieser Request liefert einen Zugriffsschlüssel eines MyCoRe-Objekts zurück.

{$id} analog zu /objects/{$id}
{$secret} Geheimnis des Zugriffsschlüssels.
{$secret_encoding} optional: Beschreibt die Codierung von {$secret_format}. Dabei wird base64url als Format unterstützt.
Format

Der Zugriffsschlüssel wird im JSON-Format zurückgeliefert.

2021.06 mycore-acl

POST /objects/{$id}/accesskeys

Dieser Request erstellt einen Zugriffsschlüssel für ein MyCoRe-Objekt. Der Zugriffsschlüssel ist standardmäßig aktiviert. Er kann in den Metadaten über isActive explizit deaktiviert werden. Die Response enthält einen Location-Header mit der URL des neuen Zugriffsschlüssels.

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

Der Zugriffsschlüssel muss im JSON-Format gesendet werden.

2021.06 mycore-acl

PUT /objects/{$id}/accesskeys/{$secret}?secret_encoding={$secret_endcoding}

Dieser Request aktualisiert einen Zugriffsschlüssel für ein MyCoRe-Objekt. Beim Update werden nur Properties berücksichtigt, die in der Anfrage enthalten sind.

{$id} analog zu /objects/{$id}
{$secret} analog zu /objects/{$id}/accesskeys/{$secret}
{$secret_encoding} analog zu /objects/{$id}/accesskeys/{$secret}
Format

Der Zugriffsschlüssel muss im JSON-Format gesendet werden.

2021.06 mycore-acl

DELETE /objects/{$id}/accesskeys/{$secret}?secret_encoding={$secret_encoding}

Dieser Request löscht einen Zugriffsschlüssel eines MyCoRe-Objekts.

{$id} analog zu /objects/{$id}
{$secret} analog zu /objects/{$id}/accesskeys/{$secret}
{$secret_encoding} analog zu /objects/{$id}/accesskeys/{$secret}

Verwaltung des Objektstatus

Dieses Feature ist derzeit prototypisch umgesetzt. Seine Implementierung kann sich ggf. noch ändern.
Es muss deshalb explizit per Property eingeschaltet werden:
 MCR.RestApi.Draft.MCRObjectState=true
DRAFT 2021.06

GET /objects/{$id}/service/state

Dieser Request liefert den Wert der state-Klassifikation im <service>-Teil des MyCoRe-Objektes zurück.

Format

Es wird ein Redirect auf den API-Endpoint /classifications mit der dazugehörigen Kategorie ausgeführt.

DRAFT 2021.06

PUT /objects/{$id}/service/state

Dieser Request setzt die state-Klassifikation im <service>-Teil des MyCoRe-Objektes.

Format

Der Wert wird als Plain-Text im Body des Requests übergeben.

Beispiel-Aufruf
curl -D - -X PUT -u administrator:*PASSWORD*  
     -H "Content-Type: text/plain" 
     -d "deleted" 
     - http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000012/service/state

 

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" 
     -d "order=1&title=%28de%29Volltextdokument&title=%28en%29fulltext%20document&classification=derivate_types%3Acontent"
     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/pdf" 
     -d "@fulltext.pdf" 
     - http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000012/derivates/skeleton_derivate_00000032/contents/fulltext.pdf

 

Verwaltung von Zugriffsschlüsseln auf Derivate

Die Zugriffsschlüssel werden im JSON-Format definiert.
2021.06 mycore-acl

GET /objects/{$id}/derivates/{$derid}/accesskeys?offset={$offset}&limit={$limit}

Dieser Request liefert eine Liste aller Zugriffsschlüssel eines MyCoRe-Derivats zurück.

{$id} analog zu /objects/{$id}
{$derid} analog zu /objects/{$id}/derivates/{$derid}
{$offset} analog zu /objects/{$id}/accesskeys
{$limit} analog zu /objects/{$id}/accesskeys
Format

Die Liste wird im JSON-Format zurückgeliefert.

2021.06 mycore-acl

GET /objects/{$id}/derivates/{$derid}/accesskeys/{$secret}?secret_encoding={$secret_encoding}

Dieser Request liefert einen Zugriffsschlüssel eines MyCoRe-Derivats zurück.

{$id} analog zu /objects/{$id}
{$derid} analog zu /objects/{$id}/derivates/{$derid}
{$secret} analog zu /objects/{$id}/accesskeys/{$secret}
{$secret_encoding} analog zu /objects/{$id}/accesskeys/{$secret}
Format

Der Zugriffsschlüssel wird im JSON-Format zurückgeliefert.

2021.06 mycore-acl

POST /objects/{$id}/derivates/{$derid}/accesskeys

Dieser Request erstellt einen Zugriffsschlüssel für ein MyCoRe-Derivat. Der Zugriffsschlüssel ist default aktiviert, wenn dieser über isActive nicht explizit deaktiviert wurde. Die Response enthält einen Location-Header mit der URL des neuen Zugriffsschlüssels.

{$id} analog zu /objects/{$id}
{$derid} analog zu /objects/{$id}/derivates/{$derid}
Format

Der Zugriffsschlüssel muss im JSON-Format gesendet werden.

2021.06 mycore-acl

PUT /objects/{$id}/derivates/{$derid}/accesskeys/{$secret}?secret_encoding={$secret_encoding}

Dieser Request aktualisiert einen Zugriffsschlüssel für ein MyCoRe-Derivat. Beim Update werden nur Properties berücksichtigt, die in der Anfrage enthalten sind.

{$id} analog zu /objects/{$id}
{$derid} analog zu /objects/{$id}/derivates/{$derid}
{$secret} analog zu /objects/{$id}/accesskeys/{$secret}
{$secret_encoding} analog zu /objects/{$id}/accesskeys/{$secret}
Format

Der Zugriffsschlüssel muss im JSON-Format gesendet werden.

2021.06 mycore-acl

DELETE /objects/{$id}/derivates/{$derid}/accesskeys/{$secret}?secret_encoding={$secret_encoding}

Dieser Request löscht einen Zugriffsschlüssel eines MyCoRe-Derivats.

{$id} analog zu /objects/{$id}
{$derid} analog zu /objects/{$id}/derivates/{$derid}
{$secret} analog zu /objects/{$id}/accesskeys/{$secret}
{$secret_encoding} analog zu /objects/{$id}/accesskeys/{$secret}

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}

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.

Beispiel-Requests

Für Entwickler

2021.06
Annotation @MCRApiDraft

Eventuell gibt es REST-Klasse/Methoden, die im Zuge der Entwicklung noch nicht stabil für den produktiven Einsatz sind. Jene können deshalb mit MCRApiDraft sowie einem Wert annotiert werden und damit explizit de- oder aktiviert werden.
Beispielsweise wird hier die Klasse MCRRestObjects mit dem Wert MCRObjects annotiert:

1
2
3
4
5
@MCRApiDraft("MCRObjects")
@Path("/objects")
public class MCRRestObjects {
  //...
}

Standardmäßig ist eine annotierte Klasse/Methode deaktiviert. Um eine annotierte Klasse/Methode zu aktiveren, muss die Konfiguration wie folgt um eine MyCoRe-Property mit dem Namen MCR.RestApi.Draft.<Wert> und true als Wert erweitert werden:

1
2
  #true|false
  MCR.RestApi.Draft.MCRObjects=true

Analog kann jene explizit mit false deaktiviert werden.