An dieser Stelle entsteht die öffentliche Dokumentation für Epigraf 5. Diese Seite ist noch in Bearbeitung. Die Dokumentation der Endpunkte wird fortlaufend ergänzt.

Das Application Programming Interface (API) von Epigraf erlaubt den Datenabruf und die Veränderung von Daten durch externe Programme über festgelegte Endpunkte. Die Endpunkte entsprechen den  URLs, die beim Navigieren der Seiten im Browser sichtbar sind. Um über diese Endpunkte anstatt der Webseiten strukturierte Formate wie JSON, XML oder CSV auszugeben, wird an den Pfad die Endung des gewünschten Formats angehängt.

Beispiel: Die Artikelliste einer Datenbank ist im Browser über /epi/epi_public/articles als Webseite abrufbar.

 

Zugang zu den Endpunkten

Für den Zugriff auf nichtöffentliche Daten wird ein Access Token benötigt, das an die URL angehängt wird, zum Beispiel:  /epi/epi_all/articles.csv?token=ABCDEFG
Das Token wird im Benutzeraccount auf Epigraf erzeugt. 

Zur Verwendung des Access Token müssen API-Berechtigungen sowohl zum Zugriff auf die entsprechende Datenbank als auch zum Zugriff auf den Endpunkt vergeben werden. Um beispielsweise den articles/index-Endpunkt mit einem Token zu erreichen, sind folgende Berechtigungen nötig:

  • User: <Benutzername>
  • Rolle: bleibt leer
  • Requested by: "api"
  • Permission type = "access"
  • Entity Type: "databank"
  • Entity name: <Name der Datenbank>
  • Entity ID: kann leer bleiben, optional ID der Datenbank
  • Permission name = "epi/articles/index"

Name und ID der Datenbank sind in der Liste der Datenbanken einsehbar.

Der Name der Berechtigung ist vom Endpunkt abgeleitet, wobei das Präfix "app" für anwendungsbezogene und das Präfix "epi" für projektdatenbankbezogene Endpunkte steht. Eine Übersicht über die Endpunkte ist in der Nutzerverwaltung zu finden. Hinweis: Während in den URLs für index-Endpunkte auf das Suffix "/index" verzichtet werden kann, ist es in der Berechtigung notwendig.

Allgemeine Parameter der Endpunkte

Gemeinsame Parameter

In allen Endpunkten muss der Pfadparameter <db> durch die ausgewählte Datenbank ersetzt werden, zum Beispiel durch "epi_public".

Paginierung und Sortierung

Jede Anfrage gibt die im limit-Parameter festgelegte Anzahl von Datensätzen zurück. Weitere Datensätze können über den page-Parameter abgefragt werden. 

Query-ParameterErläuterung
limitOptional. Standard: Anzahl der Datensätze je Seite. Der Standard variiert je nach Endpunkt, in der Regel werden 100 Datensätze zurückgegeben.
pageOptional. Standard: 1. Nummer der Seite.
totalOptional. Maximale Anzahl zurückgegebener Datensätze (auch wenn weitere verfügbar wären)
sortOptional. Gibt das Feld an, nach welchen die Daten sortiert werden. Es werden die ersten Datensätze ausgegeben, weitere Datensätze sind paginiert abrufbar. Mehrere Felder werden durch Kommata getrennt.
direction

Optional. Gibt in Verbindung mit dem sort-Parameter die Sortierrichtung an.

  • asc: Aufsteigende Sortierung
  • desc: Absteigende Sortierung

Wird nach mehreren Feldern sortiert, dann kann die Sortierrichtung für jedes Feld in einer kommaseparierten Liste angegeben werden.

idOptional: Einschränkung der Trefferliste auf einen einzelnen Datensatz

Einige Endpunkte unterstützen darüber hinaus cursor-basierte Paginierung. Bei der cursor-basierten Paginierung wird ein Referenzdatensatz als Cursor bestimmt, auf den sich die zurückgegebenen Datensätze beziehen.

Über cursor-basierte Paginierung kann auch der Kategorienbaum (epi/<db>/properties/index) gezielt auf bestimmte Ausschnitte eingegrenzt bzw. mittels seek-Parameter können gezielt festgelegte Knoten angesprungen werden. In diesem Endpunkt findet zudem eine Erweiterung der zurückgegebenen Datensätze statt: Es werden immer auch die Vorfahren der durch Filterkriterien bestimmten Datensätze zurückgegeben. Beim Anspringen werden auch vorangegangene Datensätze ausgegeben.

 

Query-ParameterErläuterung
cursorID eines Referenzdatensatzes. Es werden die in der Sortierreihenfolge folgenden Datensätze ausgegeben. Im properties/index-Endpunkt ist die Sortierung durch den Kategorienbaum vorgegeben.
directionRichtung der Sortierung: aufsteigend (Standardwert asc) oder absteigend (desc).
limitAnzahl der in einer Abfrage zurückgegebenen Datensätze. Im properties/index-Endpunkt kann die Anzahl der Datensätze größer ausfallen, da immer auch Vorfahrenknoten ergänzt werden.
childrenIn Kombination mit cursor wird im properties/index-Endpunkt bestimmt, ob die zurückgegebenen Datensätze beim nächsten Geschwisterknoten (Standardwert 0) oder beim nächsten Kindknoten (Wert 1) beginnen. Diese Angabe wird nur für die aufsteigende Sortierung berücksichtigt (direction=asc).
collapsed

In Kombination mit cursor wird im properties/index-Endpunkt bestimmt, ob die Treffermenge auf Knoten der gleichen Ebene eingeschränkt werden soll (Wert 1) oder ob alle Nachfahren ausgegeben werden (Standardwert 0). 

Dieser Parameter ist vom children- und vom cursor-Parameter abhängig: werden Kindknoten angefragt, so wird auf die Ebene der Kindknoten eingeschränkt. Andernfalls wird auf die Ebene des cursor-Knotens eingeschränkt. Ohne Angabe eines cursor-Parameters wird auf die erste Ebene eingeschränkt.

seek

ID eines Referenzdatensatzes. Anders als beim cursor-Parameter bezieht sich die Treffermenge nicht direkt auf den angegebenen Datensatz. Stattdessen werden weitere vorangegangene (Sortierrichtung desc) oder folgende (Sortierrichtung asc) Datensätze ausgegeben, wobei die Anzahl vom limit-Parameter abhängt. So kann das Umfeld eines Knotens abgefragt werden.

Dieser Parameter schließt die Verwendung der Parameter cursor, collapsed und children aus.

  
  

Felder und Spalten

Die index-Endpunkte unterstützen im columns-Parameter eine Angabe der ausgegebenen Spalten. Mehrere Spalten werden als kommaseparierte Liste angegeben.

  • Ohne Angabe, werden vorgegebene Standardfelder ausgegeben.
  • Weitere mögliche Felder werden in der Typkonfiguration im columns-Schlüssel festgelegt.
  • Angemeldete Nutzer:innen können zudem Adhoc-Felder definieren. Ein Adhoc-Feld setzt sich aus dem Bezeichner gefolgt von einem Gleichheitszeichen und einem Extraktionsschlüssel zusammen. Das Feld muss URL-kodiert werden, da es ein Gleichheitszeichen enthält. 

Als Exktraktionsschlüssel können wie in der Typkonfiguration einfache Felder des Artikelobjekts (z.B. `title`) oder auch verschachtelte Felder mit Dot-Notation angegeben werden (z.B. `project.shortname`). Um auf Listen zuzugreifen, kann ein Sternchen-Platzhalter verwendet werden (z.B. `items.{*}.value`). Die Listen können mit Bedingungen in eckigen Klammern gefiltert werden (z.B. `items.{*}[itemtype=conditions].date`). Für weitere Details siehe die CakePHP-Dokumentation zur Hash-Syntax.

Standardmäßig werden in allen ID-Feldern IRI-Pfade ausgegeben. Mit dem idents-Parameter können in einigen Endpunkten stattdessen IDs angefragt werden.

Liste der Endpunkte

GET /epi/<db>/projects/index

Eine Auflistung aller Projekte. Beispiel: /epi/epi_all/projects?term=greifswald

Query-ParameterErläuterung
termOptional. Es werden nur Projekte zurückgegeben, deren Name, Beschreibung oder IRI den Suchbegriff enthalten.
projecttypesOptional. Eine kommaseparierte Liste der Projettypen, auf die Projekte eingeschränkt werden sollen.

 

GET /epi/<db>/articles/index

Eine paginierte Auflistung von Artikeln. Identisch zu GET /epi/<db>/articles.

Query-ParameterBeschreibung
termOptional. Schränkt die Artikel im Zusammenhang mit dem field-Parameter auf diejenigen Artikel ein, in denen der Suchbegriff vorkommt.
field

Optional. Gibt im Zusammenhang mit dem term-Parameter an, welches Feld durchsucht werden soll.

  • captions: Durchsucht die Artikelnummer und den Artikeltitel.
  • articlenumber: Durchsucht die Artikelnummer.
  • title: Durchsucht den Titel des Artikels.
  • status: Durchsucht das Statusfeld des Artikels.
  • text: Durchsucht den Volltext der Artikel. Der durchsuchbare Volltext muss dazu indiziert werden, das heißt es müssen Items vom Typ "search" angelegt sein, die den Text im content-Feld enthalten.
articletypesOptional. Eine kommaseparierte Liste von Artikeltypen wie sie in der Konfiguration festgelegt sind. Es werden nur Artikel mit den angegebenen Typen ausgegeben.
projectsOptional. Eine kommaseparierte Liste von Projekt-IDs. Es werden nur Artikel ausgegeben, die zu den angegebenen Projekten gehören.
properties.<propertytype>Optional. Eine kommaseparierte Liste von Kategorien-IDs. Es werden nur Artikel ausgegeben, in denen diese Kategorien vergeben sind (über links oder items). Der Platzhalter <propertytype> wird dazu durch die interne Bezeichnung des Kategoriensystems ersetzt, wie sie in der Konfiguration festgelegt ist. Beispiel: /epi/epi_public/articles.json?properties.objecttypes=975
lat

Optional und nur in Kombination der Parameter lat und lng zutreffend.

Bei der Ausgabe einer Karte, wird diese auf den angegebenen Punkt (Parameter lat und lng) und die Zoomstufe (Parameter zoom) zentriert.

Zusätzlich können Artikel nach der Distanz zu diesem Punkt sortiert werden. Dazu wird im sort-Parameter der Wert "distance" angegeben.

lng

Optional und nur in Kombination der Parameter lat und lng zutreffend.

Bei der Ausgabe einer Karte, wird diese auf den angegebenen Punkt (Parameter lat und lng) und die Zoomstufe (Parameter zoom) zentriert.

Zusätzlich können Artikel nach der Distanz zu diesem Punkt sortiert werden. Dazu wird im sort-Parameter der Wert "distance" angegeben.

zoom

Optional und nur in Kombination mit den Parametern lat und lng zutreffend.

Bei der Ausgabe einer Karte, wird diese auf den angegebenen Punkt (Parameter lat und lng) und die Zoomstufe (Parameter zoom) zentriert.

tile

Optional.

Es werden nur Artikel ausgegeben, die Geokoordinaten im angegebenen Tile enthalten. Tiles werden nach dem Muster <zoom>/<x>/<y> gebildet, siehe https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames. Der Slash wird mit %2F URL-kodiert. Beispiel: /epi/epi_public/articles.json?tile=11%2F676%2F1066

quality

Optional und nur im Zusammenhang mit dem tiles-Parameter nutzbar. Bei der Abfrage geokodierter Daten kann die Qualitätsstufe bzw. Validität eingeschränkt werden:

  • 0 = Ungeprüft: Alle erfassten Geokoordinaten werden berücksichtigt.
  • 1 = Unsicher: Die Koordinaten müssen mindestens automatisiert auf Plausibilität überprüft worden sein.
  • 2 = Geprüft: Nur manuell geprüfte Geokoordinaten werden berücksichtigt.

Eine Einschränkung auf geprüfte Koordinaten bedeutet nicht, dass die Angaben korrekt sind. Es handelt sich stets um Vermutungen, welcher Standort am ehesten einen Zusammenhang mit dem Artikel aufweisen könnte.

template

Optional und nur für die HTML-Ausgabe zutreffend.

  • table: Es wird eine Tabelle angezeigt.
  • map: Es wird eine Karte mit geokodierten Artikeln angezeigt.
  • tiles: Es wird eine Kachelansicht mit Artikelvorschauen erzeugt.
  • lanes: Es werden Lanes ausgegeben.
  • coding: Für die Kodierung von Artikeln optimierte Ansicht, bei der Artikel im Bearbeitungsmodus angezeigt werden.
lanes

Optional, wird in Verbindung mit dem template-Parameter verwendet, um den Typ der Lanes festzulegen. Als Wert wird der Typ des Kategoriensystem angegeben, wie er in der Konfiguration festgelegt ist. Zusätzlich müssen diese Kategorien ausgewählt sein (siehe oben zum Parameter properties.<propertytype>). Beispiel: /epi/epi_public/articles.json?lanes=objecttypes&properties.objecttype=975. Das Ergebnis enthält die Kategorien im lanes-Schlüssel. 

Ist zusätzlich der lane-Parameter (Singular, siehe unten) gesetzt, wird immer nur die dadurch bestimmte Kategorie ausgegeben.

laneOptional, wird in Verbindung mit dem lanes-Parameter (Plural, siehe oben) verwendet, um die Artikel innerhalb einer Lane zu ermitteln. Dazu wird der lane-Parameter auf die ID der Kategorie gesetzt. Beispiel: /epi/epi_public/articles.json?lane=975.
columns

Optional. Kommaseparierte Liste der Felder, die in der Tabelle angezeigt werden. 

  • Ohne Angabe, werden die Standardfelder ausgegeben: articlenumber, title, norm_iri
  • Weitere mögliche Felder werden in der Typkonfiguration im columns-Schlüssel festgelegt.
  • Angemeldete Nutzer:innen können zudem Adhoc-Felder definieren. Ein Adhoc-Feld setzt sich aus dem Bezeichner gefolgt von einem Gleichheitszeichen und einem Extraktionsschlüssel zusammen. Das Feld muss URL-kodiert werden, da es ein Gleichheitszeichen enthält. 
     

Als Exktraktionsschlüssel können wie in der Typkonfiguration einfache Felder des Artikelobjekts (z.B. `title`) oder auch verschachtelte Felder mit Dot-Notation angegeben werden (z.B. `project.shortname`). Um auf Listen zuzugreifen, kann ein Sternchen-Platzhalter verwendet werden (z.B. `items.{*}.value`). Die Listen können mit Bedingungen in eckigen Klammern gefiltert werden (z.B. `items.{*}[itemtype=conditions].date`). Für weitere Details siehe die CakePHP-Dokumentation zur Hash-Syntax.

published

Optional. Es werden nur Artikel angezeigt, die mindestens dem angegebenen Publikationslevel entsprechen:

  • 0 = Erster Entwurf (drafted)
  • 1 = Datenerfassung läuft (in progress)
  • 2 = Datenerfassung abgeschlossen (complete)
  • 3 =  Veröffentlicht (published)
  • 4 = Auffindbar über die Suche (searchable)
snippets

Optional. Eine kommaseparierte Liste der Snippets, die ausgegeben werden sollen. Ein Snippet ist eine vordefinierte Zusammenstellung von Inhalten:

  • paths: Das Ergebnis enthält detaillierte Angaben zur hierarchischen Struktur von Sections und Lemmata.
  • search: Die indizierten Volltexte werden ausgegeben
  • indexes: Es werden Indizes aller Kategorien erzeugt.
  • iris: IRIs werden ausgegeben.
  • published: Das Feld mit dem Publikationsstatus wird ausgegeben.
  • tags: Alle Tags werden aus XML-Feldern extrahiert

GET /epi/<db>/properties/<propertytype>/index

Auflistung der Kategorien eines Kategorientyps.

Pfad-ParameterErläuterung
propertytypeName des Kategoriensystems. 

GET /epi/<db>/properties/merge

Vorschau, wie die Zielkategorie nach der Zusammenführung mit einer Quellkategorie aussehen würde. 

Query-ParameterErläuterung
sourceIDs der Kategorie, die aufgelöst werden soll. Mehrere IDs werden als kommaseparierte Liste angegeben.
targetID der Kategorie, in die alle Inhalte der Quellkategorie integriert werden. Abweichende Inhalte in Textfeldern werden jeweils beide übernommen.
concatSollen die Inhalte (Lemmata, Sortierschlüssel...) zusammengeführt (true) oder nur die Verweise umgelenkt (Standardwert false) werden?

Der Endpunkt kann alternativ mit Pfadparametern genutzt werden: GET /epi/<db>/properties/merge/<source>/<target>

 

POST /epi/<db>/properties/merge

Führt mehrere Kategorien zusammen, indem die Inhalte einer oder mehrerer Quellkategorien in eine Zielkategorie überführt werden. Wenn der Parameter concat gesetzt ist, werden abweichende Inhalte in Textfeldern zusammengeführt. Alle Verweise auf die Quellkategorien (zum Beispiel aus Artikeln) werden auf die Zielkategorie umgelegt. Die Quellkategorien werden anschließend gelöscht. 

Query-ParameterErläuterung
sourceIDs der Kategorie, die aufgelöst werden soll. Mehrere IDs werden als kommaseparierte Liste angegeben.
targetID der Kategorie, in die Inhalte der Quellkategorie integriert werden. 
concatSollen die Inhalte (Lemmata, Sortierschlüssel...) zusammengeführt (true) oder nur die Verweise umgelenkt (Standardwert false) werden?

Beispiel: /epi/epi_all/properties/merge?source=2,3,4&target=1

Der Endpunkt kann alternativ mit Pfadparametern genutzt werden: POST /epi/<db>/properties/merge/<source>/<target>

Wenn die Baumstruktur vom Zusammenführen betroffen ist, sollte anschließend ein POST-REquest auf den Endpunkt /epi/<db>/properties/mutate/<propertytype> ausgeführt werden.

POST /epi/<db>/properties/mutate/<propertytype>

Mit dem mutate-Endpunkt können Stapelverarbeitungen ausgeführt werden. Dazu wird im Query-Parameter task eine Aufgabe festgelegt. Für Kategorien steht momentan die Task "sort" zur Verfügung, mit der Kategorienbäume neu sortiert werden. Eine solche Sortierung ist auch dann notwendig, wenn die Baumstruktur ungültig geworden ist. Ungültige Baumstrukturen liegen vor, wenn die lft/rght-Werte nicht mehr korrekt sind, beispielsweise nach Importvorgängen oder nach Zusammenführungen von Kategorien.
 

ParameterErläuterung
taskMit task=sort wird der Kategorienbaum neu sortiert.
<propertytype>Der Kategorientyp muss als Pfadparameter angegeben werden, zum Beispiel "fonttypes".
  
PayloadErläuterung
config.params.sortby

In der Payload des POST-Requests muss das Sortierkriterium angegeben werden:

  • lemma sortiert nach dem Lemma der Kategorien
  • sortkey sortiert nach dem Sortierschlüssel der Kategorien
  • lft überprüft die vorhandene Sortierung und repariert die lft/rght-Werte
  • sortno greift die durch Epi-Desktop vorgegebene Sortierung auf und repariert die lft/rght-Werte
  


 

 

GET /epi/<db>/types/<scope>/index

In den Types wird festgelegt, welche Arten von Projekten, Artikeln, Abschnitten, Einträgen, Annotationen und Kategorien in einer Datenbank vorkommen. Der Endpunkt liefert Auflistung der Typen inklusive Konfiguration zurück.

Pfad-ParameterErläuterung
scopeOptional. Es werden nur Typen mit dem angegebenen Scope zurückgegeben: projects, articles, sections, items, links, footnotes, properties.
Query-ParameterErläuterung
termOptional. Es werden nur Typen zurückgegeben, deren Name, Beschriftung, Beschreibung oder IRI den Suchbegriff enthalten.

Datenformate

Als Kodierung wird UTF-8 verwendet, wobei nicht-sichtbare Zeichen ausgefiltert werden. Dadurch wird zum Beispiel das Steuerzeichen Unit Separator ausgefiltert.

Über den idents-Parameter wird angegeben, ob IRI-Pfade oder IDs in den ID-Feldern ausgegeben werden sollen.

Query-ParameterErläuterung
identsOptional (iri|id) Es werden standardmäßig IRI-Pfade (iri) ausgegeben. Mit dem Wert id werden IDs aus dem Tabellennamen und der Datensatz-ID zusammengesetzt.