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.

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

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

Eine paginierte Auflistung aller Artikel.

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
sortOptional. 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.

  • asc: Aufsteigende Sortierung
  • desc: Absteigende Sortierung
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.

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.

format

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.
  • coding: Für die Kodierung von Artikeln optimierte Ansicht, bei der Artikel im Bearbeitungsmodus angezeigt werden.
fieldsOptional 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:

  • 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.

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

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
sourceID der Kategorie, die aufgelöst werden soll. 
targetID 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-ParameterErläuterung
sourceID der Kategorie, die aufgelöst werden soll. 
targetID 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>

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.