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.
- Ü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.
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. Zusätzlich müssen Berechtigungen sowohl zum Zugriff auf die entsprechende Datenbank als auch zum Zugriff auf den Endpunkt vergeben werden. Um beispielsweise den articles/index-Enpunkt zu erreichen, sind folgende Berechtigungen nötig:
1. Zugang zur Datenbank
- User: <Benutzername>
- Permission Type: access
- Entity Type: databank
- Entity name: <Name der Datenbank>
- Entity ID: <ID der Datenbank>
Name und ID der Datenbank sind in der Liste der Datenbanken einsehbar.
2. Zugang zum Endpunkt
- User: <Benutzername>
- Rolle: bleibt leer
- Requested by: "api"
- Permission type = "access"
- Entity Type: "databank"
- Entity name: <Name der Datenbank>
- Entity ID: <ID der Datenbank>
- Permission name = "articles/index"
Der Permission name ist vom Endpunkt abgeleitet. Während in den URLs für index-Endpunkte auf das Suffix "/index" verzichtet werden kann, ist es in der Berechtigung notwendig.
Für automatisierte Schreibzugänge ist zusätzlich auf der epigraf-Datenbank die Berechtigung zum Ausführen von Jobs nötig:
3. Zugang zum Job-System
- User: <Benutzername>
- Rolle: bleibt leer
- Requested by: "api"
- Permission type = "access"
- Entity Type: "databank"
- Entity name: "epigraf"
- Entity ID: bleibt leer
- Permission name = "jobs/execute"
Endpunkte
Gemeinsame Parameter
In allen Endpunkten muss der Pfadparameter <db> durch die ausgewählte Datenbank ersetzt werden, zum Beispiel durch "epi_public".
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. |
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> | 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 |
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. |
direction | Optional. Gibt in Verbindung mit dem sort-Parameter die Sortierrichtung an.
|
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.
|
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. |
lane | Optional, 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. |
fields | Optional und nur für die HTML-Ausgabe zutreffend. Kommaseparierte Liste der Felder, die in der Tabelle angezeigt werden. |
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:
|
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 | ID der Kategorie, die aufgelöst werden soll. |
target | ID der Kategorie, in die alle Inhalte der Quellkategorie integriert werden. Abweichende Inhalte in Textfeldern werden jeweils beide übernommen. |
Der Endpunkt kann alternativ mit Pfadparametern genutzt werden: GET /epi/<db>/properties/merge/<source>/<target>
POST /epi/<db>/properties/merge
Führt zwei Kategorien zusammen, indem die Inhalte der Quellkategorie in die Zielkategorie überführt werden. Abweichende Inhalte in Textfeldern werden zusammengeführt. Alle Verweise auf die Quellkategorie (zum Beispiel aus Artikeln) werden auf die Zielkategorie umgelegt. Die Quellkategorie wird anschließend gelöscht.
Query-Parameter | Erläuterung |
---|---|
source | ID der Kategorie, die aufgelöst werden soll. |
target | ID der Kategorie, in die Inhalte der Quellkategorie integriert werden. |
Der Endpunkt kann alternativ mit Pfadparametern genutzt werden: POST /epi/<db>/properties/merge/<source>/<target>
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. |