REST-API

Wir stellen verschiedene REST-APIs zur freien Verfügung. REST-APIs basieren auf dem HTTP-Protokoll und können aus jeder Programmiersprache oder mit entsprechenden Tools (curl oder Postman) genutzt werden. Alle Abfragen sind mit TLS1.2 transportverschlüsselt. Das Datenaustauschformat ist JSON. Folgende Endpunkte stehen zur Verfügung:

  • Die Demo-Daten API: https://barometer.diskurslinguistik.net/public-api/
    Diese API ist frei und ohne Anmeldung nutzbar. Wir verwenden diese API für einige interaktive Visualisierungen auf https://diskursmonitor.de/barometer/.
    Im Vergleich zur Voll-API (s. u.) stellt diese API nur reduzierte Datensätze und Funktionen zu Demonstrationszwecken bereit.
    Alle Funktionen erfordern den GET-Parameter „?query=“ – dieser kann nur ein einzelnes Token umfassen (Leerzeichen nicht erlaubt / Case-Sensitiv). Wir weisen darauf hin, dass wir während der Nutzung dieser API ihre IP-Adresse speichern (nur im Arbeitsspeicher – automatische Löschung), um die API vor massenhaften Anfragen zu schützen (für komplexere und über dieses Limit hinausgehende Anfragen, nutzen Sie bitte die Voll-API – s. u.). Pro IP-Adresse können bis zu 100 Anfragen pro Stunde an diese API gerichtet werden.
    Folgende Funktionen sind nutzbar:

    • /frequ (HTTP-Verb: GET)
      Gibt die gesamten historischen Frequenzen im LIVE-Korpus aus.
      Beispiel mittels curl:

      curl --location --request GET \
      'https://barometer.diskurslinguistik.net/public-api/frequ?query=Merkel'
      

      Rückgabe: Ein JSON-Key/Value-Dictionary mit Key = Datum, Value = absolute Frequenz. Hinweis: Die relativen Frequenzen können clientseitig berechnet werden. Die Summe der Token pro Tag werden über den Public-Data-Feed veröffentlicht.
      Einschränkungen gegenüber der Voll-API: Keine.

    • /kwics (HTTP-Verb: GET)
      Simple KWIC-Suche.
      Beispiel mittels curl:

      curl --location --request GET \
      'https://barometer.diskurslinguistik.net/public-api/kwics?query=Klimekrise'
      

      Rückgabe: Ein zweidimensionales String-Array (JSON) – 0-Dimension =  Satz / 1-Dimension = Token.
      Einschränkungen gegenüber der Voll-API:

      1. Es werden nur Belege der letzten drei Tage durchsucht.
      2. Pro Dokument werden max. 2 Belege zufällig gezogen.
      3. Insgesamt werden nur 50 Belege gezogen und auf Einmaligkeit geprüft.
      4. Final werden von den einmaligen Belegen nur 10 angezeigt.
      5. Metadaten werden nicht angezeigt.
      6. Komplexe Suchabfragen sind nicht möglich.
    • /ngram (HTTP-Verb: GET)
      Gibt die gesamten historischen Frequenzen im LIVE-Korpus aus.
      Beispiel mittels curl:

      curl --location --request GET \
      'https://barometer.diskurslinguistik.net/public-api/frequ?query=Urheberrecht'
      

      Rückgabe: Im Gegensatz zu den beiden anderen Endpunkten der Demo-Daten API gibt dieser Endpunkt nur XML-Daten im Format GEXF (Version 1.2 mit viz-Erweiterungen) zurück.
      Einschränkungen gegenüber der Voll-API:

      1. Es werden nur die letzten sieben Tage durchsucht.
      2. Aus den Belegen werden 1000 Belege als Stichprobe gezogen.
      3. Es werden nur NGramme mit einer Frequenz größer 1 ausgegeben.
      4. Kein Zugriff auf die Rohdaten.
  • Zentraler Nutzerdienst: https://barometer.diskurslinguistik.net/user/
    Der zentrale Nutzerdienst verwaltet die Nutzungs- und Anmeldedaten aller Nutzer*innen, die die Voll-API verwenden. Folgende Funktionen sind implementiert:

    • /signup (HTTP-Verb: POST)
      [HINWEIS: Aktuell deaktiviert – eine Nutzung ist gegenwärtig nur über interne/manuelle Freischaltung möglich]
      Registriert einen neuen Account.
    • /validate (HTTP-Verb: POST)
      [HINWEIS: Aktuell deaktiviert – eine Nutzung ist gegenwärtig nur über interne/manuelle Freischaltung möglich]
      Bestätigt einen neuen Account oder eine Passwortänderung.
    • /resetpassword (HTTP-Verb: GET)
      [HINWEIS: Aktuell deaktiviert – eine Nutzung ist gegenwärtig nur über interne/manuelle Freischaltung möglich]
      Fordert ein neues Passwort für einen bestehenden Account an.
    • /signin (HTTP-Verb: POST)
      Meldet einen bestehenden Account an.

      • Request:
        {
        "EMail": "email",
        "Password": "mypassword"
        }
        

        Werte:

        • EMail – Die E-Mail-Adresse des registrierten Accounts (Pflichtangabe).
        • Password – Passwort des registrierten Accounts (Pflichtangabe).
      • Response:
        {
        "AssignedDataProxy": "https://barometer.diskurslinguistik.net/proxy",
        "ApiKey": "00f2a0ab-e880-DEMO-a30a-60fda505bd00",
        "SessionKey": "32e98d97-DEMO-3759-b5f9-0000f8d819e3"
        } 

        Werte:

        • AssignedDataProxy – DataProxy, der dem Account dynamisch zugewiesen wurde. Die Zuweisung ist zeitlich beschränkt (automatische Abmeldung nach 90 Minuten Inaktivität). Auf Antrag können längere oder unbefristete Sitzungen eingerichtet werden.
        • ApiKey – ApiKey des Nutzers. Identifiziert (statisch) den Account gegenüber dem DataProxy. Diese Angabe muss vertraulich behandelt
        • SessionKey – Dynamischer Key. Identifiziert die aktuelle Sitzung gegenüber dem DataProxy. Auf Antrag kann kein statischer SessionKey vergeben werden (für Webanwendungen – erfordert Nachweis einer sicheren Implementierung).
    • /mydata
      Stellt den Zugriff auf die personenbezogenen Daten des Accounts bereit. Folgende HTTP-Verben können angewendet werden:

      • GET
        email und password müssen als GET-Parameter übergeben werden. Eine vorherige Anmeldung via /signin ist nicht nötig.
        Response:

         
        { 
        "Name": "Name", 
        "FamilyName": "Family", 
        "Gender": "Liebe*r", 
        "Institution": "Universität Siegen", 
        "Job": "Linguist*in", 
        "EMail": "email", 
        "IsAcademic": true, 
        "DateCreate": "2020-02-14T01:51:54.4686351+01:00", 
        "DateLastSignin": "0001-01-01T00:00:00", 
        "Groups": [ "User" ], 
        "DailyQuota": 1000, 
        "ApiKey": "e00169b7-DEMO-9e9f-0000-18e000bc8a00", 
        "Password": "HASH(SALT+PASSWORD)", 
        "Timeout": 90 
        } 

        Werte:

        • Name – Vorname (freiwillige Angabe)
        • FamilyName – Nachname (freiwillige Angabe)
        • Gender – Gewünschte, frei definierbare Anrede (freiwillige Angabe)
        • Institution – Universität, Forschungseinrichtung etc. (freiwillige Angabe)
        • Job – Berufsbezeichnung (freiwillige Angabe)
        • EMail – E-Mail auf die dieser Account registriert ist. (kann nicht geändert werden)
        • IsAcademic – Wird der Account nur für nicht kommerzielle Forschung genutzt? (freiwillige Angabe)
        • DateCreate – Wann wurde der Account erstellt? (kann nicht geändert werden)
        • DateLastSignin – Wann wurde der Account zuletzt benutzt? (kann nicht geändert werden)
        • Groups – Welchen Nutzergruppen ist ein Account zugeordnet? Zuordnung kann nur durch Administratoren erfolgen.
        • DailyQuota – Tägliches (24 Stunden) Limit für Abfragen.
        • ApiKey – Wird zur Identifikation gegenüber DataProxy verwendet.
        • Password – Das Password wird nicht angezeigt. Das Passwort wird sicher gehasht.
        • Timeout – Nach wie vielen Minuten Inaktivität läuft eine Sitzung im DataProxy ab? (kann auf Antrag geändert werden)
      • POST
        Fügt neue Daten ein oder ändert bestehende Daten. Daten für Request müssen dem Response von GET (s. o.) entsprechen. Eine vorherige Anmeldung via /signin ist nicht nötig.
        Request:

         
        { 
        "Name": "Name", 
        "FamilyName": "Family", 
        "Gender": "Liebe*r", 
        "Institution": "Universität Siegen", 
        "Job": "Linguist*in",
        "IsAcademic": true, 
        "EMail": "email", 
        "Password": "mypassword"
        } 

        Response: 200 bei Erfolg.

      • Werte:
        • Name – Vorname (freiwillige Angabe)
        • FamilyName – Nachname (freiwillige Angabe)
        • Gender – Gewünschte, frei definierbare Anrede (freiwillige Angabe)
        • Institution – Universität, Forschungseinrichtung etc. (freiwillige Angabe)
        • Job – Berufsbezeichnung (freiwillige Angabe)
        • IsAcademic – Wird der Account nur für nicht kommerzielle Forschung genutzt? (freiwillige Angabe)
        • EMail – E-Mail auf die dieser Account registriert ist. (kann nicht geändert werden – dient zur Identifikation)
        • Password – Dient zur Identifikation und muss dem aktuellen Passwort entsprechen. Eine Änderung ist nur mittels GET /restpassword möglich (s. o.).
      • DELETE
        Löscht den kompletten Account direkt (WARNUNG: kann nicht rückgängig gemacht werden). Eine vorherige Anmeldung via /signin ist nicht nötig.
        Request:

        {
        "EMail": "email",
        "Password": "mypassword",
        "ApiKey": "00f2a0ab-e880-DEMO-a30a-60fda505bd00"
        } 

        Response: 200 bei Erfolg.
        Werte:

        • EMail – E-Mail auf die dieser Account registriert ist. (kann nicht geändert werden – dient zur Identifikation)
        • Password – Dient zur Identifikation und muss dem aktuellen Passwort entsprechen. Eine Änderung ist nur mittels GET /restpassword möglich (s. o.).
        • ApiKey – Dient als zusätzliche Sicherheit. Der ApiKey muss bekannt sein (z. B. aus vorheriger Anmeldung per /signin).
    • /ping (HTTP-Verb: GET)
      Liefer den HTTP-Code 200 zurück, wenn der Service verfügbar ist
  • Voll-API: https://barometer.diskurslinguistik.net/proxy/
    Oder jede andere URL, die von https://barometer.diskurslinguistik.net/user/signin ausgegeben wird (s. o.).
    Ein DataProxy ist ein WebService, der unabhängig vom zentralen Nutzerdienst, Daten/Analysen beritstellt. Die Nutzung ist nur nach Anmeldung und innerhalb der Aktivitätsspanne (timeout) möglich und unterliegt einem täglichen (24 Stunden) Quota. Folgende Funktionen stehen zur Verfügung:

    • /quota (HTTP-Verb: GET)
      Gibt das für den Account gesetzte Tageslimit (Quota) und den aktuellen Verbrauch aus. Es können nur solange Abfragen über den DataProxy eingestellt werden, bis das Tageslimit ausgeschöpft ist.
      Es müssen die Parameter ApiKey und SessionKey als GET-Parameter mitgegeben werden.
      Response:

      {
      "Quota": 1000,
      "Usage": 75
      } 

      Werte:

      • Quota – Tägliche Limit
      • Usage – Aktueller Verbrauch
    • /catalog (HTTP-Verb: GET)
      Gibt einen Katalog zurück, der alle verfügbaren Datenquellen, inkl. Parametern und Dokumentation beinhaltet.
      Es müssen die Parameter ApiKey und SessionKey als GET-Parameter mitgegeben werden.
      Response:

      [{
      "Arguments": [
      {
      "Help": "date format: yyyy-MM-ddT00:00:00",
      "Name": "date",
      "Limit": 1
      }],
      "ResponseProperties": [{
      "Help": "Hilfetext",
      "Name": "jobguid"
      }],
      "Help": "Get basic information about a single date",
      "Name": "source:date-value_basic",
      "Groups": null,
      "CostsPerCall": 10,
      "CostsPerKilobyte": 1,
      "GuiUrls": null,
      "Limit": null
      },
      ...
      ]

      Hinweis: Die Rückgabe ist ein Array von Katalog-Einträgen. Folgende Werte beziehen sich nur auf einen Beispiel Katalog-Eintrag.
      Werte:

      • Arguments
        Auflistung von Argumenten. Alle Argument sind verpflichtend.

        • Help – Information zum Argument. Ggf. wie Daten zu formatieren sind (Datentyp) oder welche Werte/Wertbereiche gültig sind.
        • Name – Name des Arguments. Siehe /query (s. u.).
        • Limit – ggf. Informationen zu Limits für die Abfrage.
      • ResponseProperties
        Informationen zur Ausgestaltung der Rückgabewerte.
      • Help
        Allgemeine Hilfe – welche Funktion/Daten stellt der Katalog-Eintrag bereit.
      • Name
        Name des Katalog-Eintrags.
      • Groups
        Wenn null ist der Zugang frei für alle Nutzergruppen. Wird hier eine oder mehrere Nutzergruppen aufgeführt, ist es notwendig, dass der Account, der eine Anfrage startet zu dieser Nutzergruppe gehört. s. o. /user/mydata GET
      • CostsPerCall
        Kosten (Quota) die pro Aufruf berechnet werden. Usage + CostsPerCall müssen kleiner sein als Quota (pre Call-Berechnung).
      • CostsPerKilobyte
        Kosten (Quota) die pro abgerufenes Kilobyte berechnet werden (gerundet). Wird erst nach einem Call berechnet.
      • GuiUrls
        Ggf. Empfehelungen für grafische Visualisierungen zu den Daten.
      • Limit
        Ggf. zusätzliche Informationen zu Limits.
    • /query
      Führt die eigentlich Datenabfrage durch.
      Request:

      {
      "ApiKey": "290001d-9005-DEMO-44e9-0009b6AB3A",
      "SessionKey": "9e00bf07-DEMO-8888-a009-b0007e22AAA",
      "Name": "openthesaurus",
      "Arguments":
      {
      "query": "Frieden"
      }
      }
      

      Werte:

      • ApiKey – Identifiziert den Account gegenüber dem DataProxy.
      • SessionKey – Identifiziert die aktuelle Sitzung.
      • Name – Name der Datenquelle – s. o. /catalog
      • Arguments – Argumente die von der Datenquelle benötitgt werden – s. o. /catalog
    • /udcall
      Diese Funktion ist nicht von extern aufrufbar. Der DataProxy überprüft, ob Anfragen an diesen Endpunkt von einer Liste zertifizierter UserData-Services kommen. UserData können darüber die Verfügbarkeit des DataProxys prüfen und Nutzer zuweisen.