zum Hauptinhalt springen

API

Die RESTful API erlaubt den lesenden Zugriff für Fremdsysteme auf alle Inhalte des Systems. Die Ausgabe der Daten erfolgt im JSON Format. Standardmäßig ist die Schnittstelle deaktiviert und muss explizit in der Konfiguration aktiviert und konfiguriert werden.
Beispielaufruf der API (Ausgabe der News dieser Seite als JSON)

Konfiguration

  • Zugriff auf die API erlauben
    Legt generell fest, ob die API frei geschaltet werden soll
  • Nur veröffentlichte Inhalte ausgeben
    wenn diese Option gesetzt ist, werden nur Einträge von der API zurück gegeben, die aktiviert, bzw. veröffentlicht sind (Auge-Symbol im Backend)
  • Erfolgreiche Aufrufe protokollieren
    wenn aktiviert, werden alle Anfragen samt URL und IP des Aufrufers in der sys.log Datei protokolliert. Falls deaktiviert werden nur fehlgeschlagene Aufrufe als Warnung in die sys.log geschrieben.
  • Anfragen Limit
    falls hier ein positiver Wert eingetragen wird, gilt dieses Kontingent pro IP Adresse im Zeitfenster des Limits (Minute, Stunde oder Tag). Werden in einem Zeitfenster mehr Anfragen gestellt, wird mit der Aktion bei Überschreitung des Limits definiert, ob weitere Anfragen langsamer beantwortet werden sollen (ca. 3 Sekunden verzögert), oder ob anstatt der Daten eine Fehlermeldung an den Aufrufer zurück gegeben werden soll.
  • Gesperrte Tabellen
    hier können Tabellennamen aus der Datenbank eingetragen werden, die nicht über die API abfragbar sein sollen. Einige Tabellenfelder werden grundsätzlich nicht ausgegeben, auch wenn die Tabelle selbst nicht gesperrt ist (z.B. Passwort-Hashes).
Konfigurationseinstellungen für die API
Konfigurationseinstellungen für die API

Basisaufbau einer API Anfrage

API Anfragen sind nichts anderes als URLs, wie sie auch zum Aufrufen von Seiten des Systems verwendet werden. Sie beginnen immer mit dem Pfad "/api/" nach dem Domainnamen. Die API dieser Website wird also immer mit folgendem Pfad beginnen:
https://www.martin-eberhardt.com/api/

Anschließend erfolgt die Angabe der gewünschten API-Version (bisher gibt es nur die erste Version):
https://www.martin-eberhardt.com/api/V1/

Darauf folgt der Name einer Datenbanktabelle, die abgefragt werden soll (z.B. "news") bei diesem Pfad sind bereits alle Mindestangaben vorhanden, um eine unsortierte und ungefilterte Liste auszugeben:
https://www.martin-eberhardt.com/api/V1/news/

Um anstatt einer Liste einen einzelnen Eintrag abzufragen, kann man die ID des gewünschten Datensatzes als Pfadangabe ergänzen:
https://www.martin-eberhardt.com/api/V1/news/50/

Verfeinerung der Anfrage durch Parameter

Seitensteuerung

  • per_page
    Standardmäßig werden maximal 100 Einträge zurück geliefert, der Wert kann aber über den Parameter "per_page" im Bereich von 1-1000 angepasst werden:
    /api/V1/news/?per_page=3
  • add_envelope
    Um zu erfahren, wie viele Einträge und Seiten eine Liste hat, bietet sich der Parameter "add_envelope" an. Die API reichert die Daten dann mit diversen Zusatzinformationen wie Links zu Folgeseite und Vorgängerseite an:
    /api/V1/news/?per_page=3&add_envelope=1
  • page
    Schließlich kann mit dem Parameter "page" direkt eine Seite ausgwählt werden:
    /api/V1/news/?per_page=3&add_envelope=1&page=2
Liste von news Einträgen als JSON
JSON array ohne Umschlag (add_envelope)
JSON Assgabe des envelopes
JSON Ausgabe des Umschlags

Verknüpfte Daten ausgeben

Datensätze können über Fremdschlüsselfelder und sog. Referenzen mit anderen Datensätzen verknüpft sein. Um diese verknüpften Daten bei einer Anfrage mit ausgeben zu lassen gibt es zwei Parameter.

  • add_fk
    Gibt die Daten, die per Fremdschlüssel (Foreign Key) verknüpft sind mit aus:
    /api/V1/news/50?add_fk=1
    unter "maid" wird der Datensatz aus der Tabelle "mandant", der über das Feld "maid" im news Datensatz verknüpft ist angezeigt (Siehe Bild "JSON Ausgabe der Fremdschlüssel")
  • add_refs
    Gibt die Referenzen aus, in diesem Beispiel die News-Kategorie "Mae CMS Version" ist (Siehe Bild JSON Ausgabe der Referenzen)
    /api/V1/news/50?add_refs=1

Jedes Element in der JSON Ausgabe verfügt unter der Eigenschaft "_link" über einen Link zum direkten Aufruf des Elements über die API. Außerdem ist in der Eigenschaft "_table" ersichtlich, aus welcher Datenbanktabelle der Datensatz stammt.

Manche Objekte wie Bilder oder Seiten, für die es einen Frontend Link gibt, enthalten diesen in der Eigenschaft "_webUrl".

JSON Ausgabe der Fremdschlüssel
JSON Ausgabe der Fremdschlüssel
JSON Ausgabe der Referenzen
JSON Ausgabe der Referenzen

Filtern und Sortieren der Ausgabe

Um das Arbeiten mit der Schnittstellenausgabe zu vereinfachen und unnötigen Traffic zu vermeiden, bietet die API verschiedene Parameter:

  • f_[Feldname]=[Wert]
    Mit "f_" kann die Ausgabe nach Feldwerten gefiltert werden. In diesem Beispiel sollen nur veröffentlichte (published) Newsbeiträge mit dem Titel "1.10.0" ausgegeben werden:
    /api/V1/news?f_title=1.10.0&f_published=true
    Bei Systemen mit mehreren Sprachen/Domains ist es z.B. bei news oder events wichtig, das Fremdschlüsselfeld "maid" nach der gewünschten Sprache/Domain aus der Tabelle "mandant" zu filtern.
  • ref_[Referenztyp]=[id]
    Um nach Referenzen zu filtern muss man sich zunächst über "add_refs" einen Überblick über die verfügbaren Referenztypen verschaffen. (Siehe Bild "JSON Ausgabe der Referenzen").
    Im Beispiel filtern wir nach der Newskategorie "Mae CMS Version", die über den Typ "newsCats" referenziert wird:
    /api/V1/news?ref_newsCats=2
  • fields
    Um nur einen Teil der verfügbaren Felder zu erhalten kann eine kommagetrennte Liste mit Feldnamen über den Parameter "fields" angegeben werden:
    /api/V1/news/50?fields=id,title,newsTime
    (Siehe Bild "JSON Ausgabe mit reduzierter Feldliste")
  • sort_by
    Die Ausgabe kann nach mehreren Feldern auf- oder absteigend sortiert werden.
    In diesem Beispiel wird absteigend (descending) nach dem Datum (newsTime) und innerhalb des selben Datums aufsteigend nach der "id" sortiert:
    /api/V1/news?sort_by=newsTime.desc,id
JSON Ausgabe mit reduzierter Feldliste
JSON Ausgabe mit reduzierter Feldliste