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.
Die gesamte Epigraf-Anwendung ist ein Application Programming Interface (API). Epigraf erlaubt den Datenabruf und die Veränderung von Daten durch externe Programme über festgelegte Endpunkte. Prinzipiell kann Epigraf auch als Backend für unabhängig gehostete Frontends verwendet werden. Daten werden dazu entweder strukturiert (JSON) ausgetauscht oder es werden spezifische, gerenderte HTML-Komponenten wie die Artikelliste (ohne das Layout) per API-Zugang in ein Frontend eingebettet.
Die Endpunkte entsprechen den URLs, die beim Navigieren der Seiten im Browser sichtbar sind. Um über diese Endpunkte anstatt der HTML-Webseiten strukturierte Formate auszugeben, wird an den Pfad die Endung des gewünschten Formats angehängt:
- Das XML-Format umfasst alle Inhalte einer Seite und ist hierarchisch strukturiert. Beispielsweise enthalten Artikel-Elemente alle Abschnitte. Es ist gleichzeitig das Ausgangsformat für Exporte über Pipelines.
- Das JSON-Format ist hierarchisch strukturiert, in der Regel aber kompakter als XML und für weitere Anwendungen leichter zu verarbeiten.
- Das CSV-Format enthält tabellarische Daten und ist mit vielen Statistikprogrammen kompatibel. Epigraf gibt Datensätze unterschiedlicher Hierarchieebenen (zum Beispiel Artikel und deren Abschnitte) untereinander in einzelnen Zeilen aus. Die hierarchische Zuordnung wird über Verknüpfungen von IDs abgebildet.
Im Fußbereich der Seiten finden sich entsprechende Buttons. Alternativ kann die im Browser angezeigte URL so abgewandelt werden, dass der Pfad mit dem Dateiformat endet (.xml, .json, .csv).
Beispiel: Die Artikelliste einer Datenbank ist im Browser über /epi/epi_public/articles als Webseite abrufbar.
- Über /epi/epi_public/articles.json wird diese Liste als JSON ausgegeben.
- Über /epi/epi_public/articles.xml werden die Daten im XML-Format ausgegeben.
- Über /epi/epi_public/articles.csv wird eine CSV-Tabelle ausgegeben.
Seiten mit tabellarischen Inhalten werden Hydra-kompatibel ausgegeben, sodass ein Harvesting von Kollektionen ermöglicht wird. Wenn eine entsprechende Konfiguration eingerichtet ist, lassen sich einzelne Artikel in RDF-kompatiblen Triple-Formaten ausgeben.
- JSON-LD (jsonld-Endung)
- Turtle (ttl-Endung)
- RDF/XML (rdf-Endung)
Neben dem Abruf strukturierter Daten, können folgende gerenderte Ansichten erzeugt werden:
- HTML (ohne Endung): Interaktive Webseite für die Darstellung im Browser. Über den show-Parameter können einzelne Elemente für die Einbettung in Webseiten ausgewählt werden. Über den theme-Parameter wird die CSS-Gestaltung beeinflusst.
- Markdown (md-Endung): Darstellung der Artikelinhalte als Textformat.
Zugang zu den Endpunkten
Für den Zugriff auf nichtöffentliche Daten und für Schreibzugriffe wird ein Access Token benötigt, das an die URL angehängt oder als Bearer Token mitgesendet wird, zum Beispiel: /epi/epi_all/articles.csv?token=ABCDEFG. Das Token wird im Benutzeraccount von 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"
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-Parameter | Erläuterung |
|---|---|
| limit | Optional. Standard: Anzahl der Datensätze je Seite. Der Standard variiert je nach Endpunkt, in der Regel werden 100 Datensätze zurückgegeben. |
| page | Optional. Standard: 1. Nummer der Seite. |
| total | Optional. Maximale Anzahl zurückgegebener Datensätze (auch wenn weitere verfügbar wären) |
| sort | Optional. 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.
Wird nach mehreren Feldern sortiert, dann kann die Sortierrichtung für jedes Feld in einer kommaseparierten Liste angegeben werden. |
| id | Optional: 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-Parameter | Erläuterung |
|---|---|
| cursor | ID eines Referenzdatensatzes. Es werden die in der Sortierreihenfolge folgenden Datensätze ausgegeben. Im properties/index-Endpunkt ist die Sortierung durch den Kategorienbaum vorgegeben. |
| direction | Richtung der Sortierung: aufsteigend (Standardwert asc) oder absteigend (desc). |
| limit | Anzahl 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. |
| children | In 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 Dieser Parameter ist vom |
| seek | ID eines Referenzdatensatzes. Anders als beim Dieser Parameter schließt die Verwendung der Parameter |
Felder, Spalten und Blöcke
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.
Für die HTML-Ausgaben können explizit bestimmte Seitenbereiche angefordert werden. Auf diese Weise lässt sich etwa der Inhaltsbereich ohne Seitenleisten in externe Seiten einbetten. Dazu wird im show-Parameter eine kommaseparierte Liste folgender Elemente verwendet:
- mainmenu: Das Hauptmenü.
- searchbar: Die Suchleiste in Tabellenansichten.
- content: Der Inhaltsbereich.
- footer: Der Fußbereich
- leftsidebar: Die linke Seitenleiste.
- rightsidebar: Die linke Seitenleiste.
Über den theme-Parameter kann das Styling der Ansicht beeinflusst werden. Das Theme "minimal" erzeugt eine kompaktere Ansicht mit reduzierten Außenabständen, die insbesondere bei der Einbettung über iframes nützlich ist.
Der flow-Parameter bestimmt, wohin Klicks auf einzelne Datensätze in Kollektionen führen: frame, popup oder tab.
Verfügbare Endpunkte
Alle Endpunkte sind nach dem gleichen Muster aufgebaut. Zu unterscheiden ist zwischen globalen Endpunkten und datenbankspezifischen Endpunkten:
- Globale Endpunkte setzen sich einem Controller, der in der Regel einer Datenbanktabelle entspricht, der auszuführenden Action und ggf. weiteren Parametern zusammen:
/<controller>/<action>?<parameter> - Datenbankspezifische Endpunkte enthalten zusätzlich das Pfadsegment
epiund einen Datenbanknamen<db>:/epi/<db>/<controller>/<action>?<parameter>
Typischerweise stellt ein Controller folgende Actions zur Verfügung
- index
- view
- show
- edit
- add
- delete
- import
- transfer
- mutate
Liste der Endpunkte
Projects
GET /epi/<db>/projects/index
Eine Auflistung aller Projekte. Beispiel: /epi/epi_all/projects?term=greifswald
| Query-Parameter | Erläuterung |
|---|---|
| term | Optional. Es werden nur Projekte zurückgegeben, deren Name, Beschreibung oder IRI den Suchbegriff enthalten. |
| projecttypes | Optional. Eine kommaseparierte Liste der Projettypen, auf die Projekte eingeschränkt werden sollen. |
Articles
GET /epi/<db>/articles/index
Eine paginierte Auflistung von Artikeln. Identisch zu GET /epi/<db>/articles.
| Query-Parameter | Beschreibung |
|---|---|
| term | Optional. 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.
|
| articletypes | Optional. Eine kommaseparierte Liste von Artikeltypen wie sie in der Konfiguration festgelegt sind. Es werden nur Artikel mit den angegebenen Typen ausgegeben. |
| projects | Optional. Eine kommaseparierte Liste von Projekt-IDs. Es werden nur Artikel ausgegeben, die zu den angegebenen Projekten gehören. |
| properties.<propertytype>.selected | 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.selected=975 |
| properties.<propertytype>.flags | Optional. Eine kommaseparierte Liste von Optionen im Zusammenhang mit dem Kategorienfilter. Möglicher Optionen
|
| 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:
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.
|
| columns | Optional. Kommaseparierte Liste der Felder, die in der Tabelle angezeigt werden.
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:
|
| snippets | Optional. Eine kommaseparierte Liste der Snippets, die ausgegeben werden sollen. Ein Snippet ist eine vordefinierte Zusammenstellung von Inhalten:
|
| details | Optional (experimentell). Eine kommaseparierte Liste mit Extraktionsschlüsseln. Die extrahierten Inhalte werden in der tabellarischen Ansicht als Suchergebnisse dargestellt. Darüber lassen sich auch annotierte Segmente darstellen, Beispiel: /articles/index?details=items.*.tags.*. |
| idents | Optional.
|
POST /epi/<db>/articles/import
Importiert Artikel inklusive aller dazugehörigen Daten. Die Datenstruktur muss dem Relational Article Model entsprechen. Es werden drei Varianten unterstützt: 1. Importieren einer bereits hochgeladenen Datei. 2. Hochladen und importieren einer Datei. 3. Importieren von JSON-Daten.
| Post-Parameter | Erläuterung |
|---|---|
| filename | When importing files or folders already present on the server: file name or folder name on the server, relative to the import folder of the database. The files must be XML or CSV. Folders can contain multiple XML files. |
| file | When uploading and at the same time importing a file: The file content following the Relational Article Model in CSV or XML format. |
| data | When posting JSON data: The data array according to the Relational Article Model. |
Beispiel: /epi/epi_movies/articles/import?filename=newmovies.csv
Sections
POST /epi/<db>/sections/move/<id>
Move sections within an article below or behind a reference section.
| Parameter | Erläuterung |
|---|---|
| <id> | ID of the section to move |
| Payload | Erläuterung |
|---|---|
| reference_id | ID of a reference section |
| reference_pos | Relation of the reference section to the section: parent or preceding |
Properties
GET /epi/<db>/properties/<propertytype>/index
Auflistung der Kategorien eines Kategorientyps.
| Pfad-Parameter | Erläuterung |
|---|---|
| propertytype | Name des Kategoriensystems. |
GET /epi/<db>/properties/merge
Vorschau, wie die Zielkategorie nach der Zusammenführung mit einer Quellkategorie aussehen würde.
| Query-Parameter | Erläuterung |
|---|---|
| source | IDs der Kategorie, die aufgelöst werden soll. Mehrere IDs werden als kommaseparierte Liste angegeben. |
| target | ID der Kategorie, in die alle Inhalte der Quellkategorie integriert werden. Abweichende Inhalte in Textfeldern werden jeweils beide übernommen. |
| concat | Sollen 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-Parameter | Erläuterung |
|---|---|
| source | IDs der Kategorie, die aufgelöst werden soll. Mehrere IDs werden als kommaseparierte Liste angegeben. |
| target | ID der Kategorie, in die Inhalte der Quellkategorie integriert werden. |
| concat | Sollen 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.
| Parameter | Erläuterung |
|---|---|
| task | Mit task=sort wird der Kategorienbaum neu sortiert. |
| <propertytype> | Der Kategorientyp muss als Pfadparameter angegeben werden, zum Beispiel "fonttypes". |
| Payload | Erläuterung |
|---|---|
| config.params.sortby | In der Payload des POST-Requests muss das Sortierkriterium angegeben werden:
|
Types
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-Parameter | Erläuterung |
|---|---|
| scope | Optional. Es werden nur Typen mit dem angegebenen Scope zurückgegeben: projects, articles, sections, items, links, footnotes, properties. |
| Query-Parameter | Erläuterung |
|---|---|
| term | Optional. 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-Parameter | Erläuterung |
|---|---|
| idents | Optional (iri|id) Es werden standardmäßig IRI-Pfade (iri) ausgegeben. Mit dem Wert id werden IDs aus dem Tabellennamen und der Datensatz-ID zusammengesetzt. |