REST-API v2

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

• http://www.mycore.de/mir/api/v2/objects
• http://www.mycore.de/mir/api/v2/objects.json

GET /objects/{$id}

Dieser Request liefert die internen XML-Metadaten eines MyCoRe-Objektes zurück.

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

Beispiel-Requests

• http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003
• http://www.mycore.de/mir/api/v2/objects/mir_mods_03
• http://rosdok.uni-rostock.de/api/v2/objects/recordIdentifier:rosdok%252Fppn746606281

 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.

Beispiel-Requests

• http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003/metadata
• http://www.mycore.de/mir/api/v2/objects/mir_mods_03/metadata
• http://rosdok.uni-rostock.de/api/v2/objects/recordIdentifier:rosdok%252Fppn746606281/metadata

 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>

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>

Verwaltung von Zugriffsschlüsseln auf Objekte

Verwaltung des Objektstatus

 MCR.RestApi.Draft.MCRObjectState=true

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

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

• http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003/derivates
• http://www.mycore.de/mir/api/v1/objects/mir_mods_00000003/derivates.xml

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

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

Beispiel-Requests

• http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000001/derivates/skeleton_derivate_00000003
• http://localhost:8080/skeleton/api/v2/objects/skeleton_simpledoc_00000001/derivates/derivateType:thumbnail

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.

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

• http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003
  /derivates/Document_derivate_00000002/contents
• http://www.mycore.de/mir/api/v2/objects/mir_mods_00000003
  /derivates/Document_derivate_00000002/contents/document.pdf

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

Beispiel-Requests

• http://www.mycore.de/mir/servlets/MCRFileNodeServlet/Document_derivate_00000002/handreichung-publikationsfonds.pdf
• http://rosdok.uni-rostock.de/file/rosdok_document_0000006760/rosdok_derivate_0000025090/ppn746606281.cover.jpg

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

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

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

• http://www.mycore.de/mir/api/v2/classifications
• http://www.mycore.de/mir/api/v2/classifications.json

GET /classifications/{$classid}

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

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

• http://www.mycore.de/mir/api/v2/classifications/state
• http://www.mycore.de/mir/api/v2/classifications/state.xml

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.