2019.06 2020.06

REST-API

Die REST-API kann vor allem durch externe Tools für den Zugriff auf MyCoRe-Objekte, Klassifikationen, Messages und Suchanfragen benutzt werden.

Allgemeines

Mit dem LTS 2015.05 stellt MyCoRe eine REST-Schnittstelle bereit, die einen nur-lesenden Zugriff auf MyCoRe-Objekte, -Derivate, Klassifikationen, I18N-Texte und den Suchindex ermöglicht. Sämtliche Aufrufe erfolgen per GET-Request.
Die Basis-URL der REST-API lautet: {$WebApplicationBaseURL}api/v1.

Seit Release 2020.06 gibt es eine Version 2 der MyCoRe-Rest-Schnittstelle. Die Dokumentation dazu ist unter REST v2 zu finden.

Zugriffsschutz

Seit 2017.06 wird die Nutzung der REST-API 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:/v1/objects) zusätzlich beschränkt werden.

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.

Metadatenobjekte und Derivate anzeigen

/objects

Auflistung aller MyCoRe-Objekte

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

Parameter

format Mögliche Werte sind: xml (default) und json.

filter

enhält eine durch Semikolon ; getrennte Liste von Schlüssel-Wert-Paaren. Schlüssel und Wert sind durch Doppelpunkt : getrennt, folgende Schlüssel können verwendet werden:

`project`	die MyCoRe-Project-ID (erster Teil einer MyCoRe-ID)
`type`	der MyCoRe-Objekttyp (mittlerer Teil einer MyCoRe-ID)
`lastModifiedBefore`	filtert Objekte, deren letzte Änderung vor dem (im UTC-Format) angegebenen Datum erfolgte.
`lastModifiedAfter`	filtert Objekte, deren letzte Änderung nach dem (im UTC-Format) angebenen Datum erfolgte.

sort

Sortierfeld und Sortierreihenfolge durch Doppelpunkt getrennt (sort_field:sort_order).

Folgende Werte sind zugelassen:

`sort_field`	`ID` oder `lastModified`
`sort_order`	`asc` oder `desc`

Beispiel-Requests

/objects/{$id}

Anzeige eines einzelnen Objektes

Dieser Request liefert das interne XML eines MyCoRe-Objektes zurück.

{$id}

entspricht im Standardfall der MyCoRe-Object-ID,
im Spezialfall hat die ID die Form prefix:other-id

prefix mögliche Werte sind: mcr für eine MyCoRe-Object-ID (default) und recordIdentifier für ein gleichnamiges Suchfeld im Solr-Index (z.B. belegt durch den Wert mods:recordIdentifier beim Rostocker Dokumentenserver RosDok)

Parameter

style einziger Wert ist derivatedetails,
damit wird das XML um Informationen aus den verknüpften Derivaten angereichert

Beispiel-Requests

/objects/{$id}/derivates

Auflistung der Derivate

diese URL liefert eine Liste der zu einem MyCoRe-Objekt gehörenden Derivate

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

Parameter

format mögliche Werte sind: xml (default) und json

sort

Sortierfeld und Sortierreihenfolge durch Doppelpunkt getrennt (sort_field:sort_order), folgende Werte sind zugelassen:

`sort_field`	`ID` oder `lastModified`
`sort_order`	`asc` oder `desc`

Beispiel-Requests

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

Anzeige eines einzelnen 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,
im Spezialfall hat die ID die Form prefix:other-id

prefix einziger Wert ist label für das Label eines Derivates

Beispiel-Requests

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

Öffnen der Hauptdatei eines Derivates

Mit diesem Request lässt sich die Hauptdatei eines Derivates anzeigen. Es erfolgt ein Redirect-Request auf die MyCoRe File API.

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

Beispiel-Requests

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

Auflistung der Dateien eines Derivates

Mit diesem Request enthält man ein Directory-Listing aller im Derivate abgelegten Dateien.

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

Parameter

`format`	mögliche Werte sind: `xml` (default) und `json`
`depth`	Anzahl der Verzeichnisebenen, die zurückgeliefert werden sollen (default: `-1` für alle)

Beispiel-Requests

Anzeige / Download einer Datei aus einem Derivat

Diese Funktionalität wird nicht über die REST-API, sondern über die File-API bereitgestellt. Die URL kann man dem @href-Attribut der Auflistung der Dateien entnehmen (siehe obige Beispiel-Requests für /objects/{$id}/derivates/{$derid}/contents).

Beispiel-Requests

Klassifikationen anzeigen

/classifications

Auflistung aller Klassifikationen

Dieser Request listet alle in der Anwendung installierten Klassifikationen auf.

Parameter

format mögliche Werte sind: json (default) und xml

Beispiel-Requests

/classifications/{$classid}

Anzeigen einer Klassifikation

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

{$classid} entspricht der ID einer Klassifikation

Parameter

format mögliche Werte sind: xml (default) und json

filter

enhält eine durch Semikolon ; getrennte Liste von Schlüssel-Wert-Paaren, Schlüssel und Wert sind durch Doppelpunkt : getrennt, für einige Schlüssel wurden keine Werte definiert, folgende Schlüssel können verwendet werden:

`lang`	Es werden nur Label der Sprache zurückgegebenen, die dem angegebenen ISO-Kürzel enstpricht. Wenn `lang` nicht gesetzt ist, werden Label für sämtliche definierte Sprachen zurückgegeben.
`root`	Es wird nur ein Teilbaum der Klassifikation zurückgegeben. Dieser hat als Root-Knoten die Kategorie, deren ID hier spezifiziert wurde.
`nonempty`	[ohne Wert] Es werden nur Kategorien ausgegeben, die auch mit Objekten verknüpft sind.

style

enhält eine durch Semikolon ; getrennte Liste von Werten, die die Ausgabe der Klassifikation steuert. Derzeit wird style nur mit format=json verwendet.

`checkboxtree`	Die JSON-Ausgabe erfolgt so, dass sie als Eingabe für die Javascript-Komponente Dijit CheckBox Tree verwendet werden kann.
`checked`	nur gemeinsam mit `checkboxtree` zu verwenden) Alle Einträge werden mit dem Parameter `checked:true` ausgegeben.
`jstree`	Die JSON-Ausgabe erfolgt so, dass sie als Eingabe für die Javascript-Komponente jsTree verwendet werden kann. Das HTML-Beispiel jstree_demo.html zeigt, wie man mittels AJAX und `jsTree` Klassifikationen in eine Webseite einbetten kann.
`opened`	(nur gemeinsam mit `jstree` zu verwenden) Der komplette Baum wird geöffnet dargestellt.
`disabled`	(nur gemeinsam mit `jstree` zu verwenden) Der komplette Baum wird readOnly dargestellt.
`selected`	(nur gemeinsam mit `jstree` zu verwenden) Alle Einträge des Baumes werden ausgewählt.

callback

Für format=json wird die Ausgabe in einer Javascript-Callback-Funktion mit dem angegebenen Namen gekapselt. Mittels JSONP lässt sich so die Same-Origin-Policy des Webbrowsers umgehen.

Beispiel-Requests

I18N-Support

/messages

Abruf aller Message-Properties

Dieser Request listet alle in der Anwendung definierten Message-Properties auf.

Parameter

`format`	mögliche Werte sind: `property` (default, Standard-Property-Format), `json` und `xml`
`lang`	ein von der Anwendung unterstütztes Sprachkürzel (default: `de`)
`filter`	eine mit Semikolon `;` getrennte Liste von Message-Key-Prefixes

Beispiel-Requests

/messages/{$key}

Anzeigen eines Message-Eintrages

Dieser Request zeigt ein einzelnes Message-Property an.

{$key} entspricht einem Message-Key

Parameter

`format`	mögliche Werte sind: `text` (default), `property` (Standard-Property-Format), `xml` und `json`
`lang`	ein von der Anwendung unterstütztes ISO-Sprachkürzel (default: `de`)

Beispiel-Requests

Suche

Die REST-Schnittstelle zur Suche soll vor allem als Frontend für den in der MyCoRe-Anwendung verwendeten SOLR-Server fungieren. In der Regel werden die Ausgaben des SOLR-Servers unverändert ausgeliefert.

/search

Stellen einer Suchanfrage

Achtung: prototypische Implementierung

Parameter

Die Parameter orientieren sich an der SOLR-Syntax. Weitere Informationen über die Syntax sind in der SOLR-Dokumentation zu finden.

q eine Such-Anfrage in SOLR-Query-Syntax

sort

Sortierfeld und Sortierreihenfole in SOLR-Syntax mit Leerzeichen getrennt (sort_field sort_order).

`sort_field`	ein in der MyCoRe-Anwendung definiertes Suchfeld z.B.: id, category, recordIdentifier
`sort_order`	erlaubte Werte sind: `asc` und `desc`

wt

Rückgabeformat, erlaubte Werte sind u.a.: xml (default), json oder csv.

start

für Treffernavigation: Position des ersten zurückgegebenen Treffers in der Trefferliste im Bezug auf die Gesamttreffermenge.

rows

für Treffernavigation: Anzahl der Treffer (default 10), die in der Trefferliste zurückgegeben werden sollen.

fq

Filter-Query: zusätzliche Query zum Einschränken der Treffermenge. Diese Query hat keine Auswirkungen auf die Berechnung des Rankings (score) eines Treffers.

fl

Field-List: beschränkt die in der Trefferliste zurückgelieferten Felder.

facet

facet=true erzeugt Informationen über Facetten in der SOLR Query Response.

facet.field

wiederholbarer Parameter, der die auszugebenden Facettenfelder spezifiziert.

facet.sort

gibt an, wie sortiert werden soll. Mögliche Werte sind count (nach Anzahl, default) und index.

facet.limit

gibt die Anzahl der im Response enthaltenen Facetten an, Default-Wert ist 100. Eine negative Angabe bedeutet unbegrenzt.

json.wrf

Name der Wrapper-Funktion, die die JSON-Ausgabe umschließt. Diese wird in AJAX/Javascript als Callback Funktion aufgerufen.

Das HTML-Beispiel js_counting.html zeigt, wie man ein Suchergebnis per AJAX und JQuery in eine Webseite einbettet.