REST Protokoll¶

Nachfolgend werden die Methoden und Parameter zum Zugriff auf das REST-API des Servers beschrieben. Wenn URLs variable Komponenten enthalten, werden diese {in geschweiften Klammern} angegeben und müssen bei der tatsächlichen Verwendung der URLs durch die korrekten Werte ersetzt werden.

Soweit in den URLs des REST-Protokolls Umlaute oder andere Zeichen außerhalb des ASCII-Bereichs verwendet werden sollen, müssen diese in URL-Codierung (vgl. https://de.wikipedia.org/wiki/URL-Kodierung) angegeben werden.

Bemerkung

Für die numerischen Werte in der URL-Codierung wird vorausgesetzt, dass sie sich auf die hexadezimale Angabe der UTF-8-Darstellung des betreffenden Zeichens beziehen.

Für die Codierung der Umlaute in URLs kann folgende Tabelle verwendet werden:

Zeichen	Unicode	UTF-8 hexadezimal
Ä	U+00C4	%C3%84
Ö	U+00D6	%C3%96
Ü	U+00DC	%C3%9C
ä	U+00E4	%C3%A4
ö	U+00F6	%C3%B6
ü	U+00FC	%C3%BC

Falls in einer URL z. B. das Wort „für“ verwendet werden soll, ist es daher durch die Zeichenfolge „f%C3%BCr“ zu kodieren.

Allgemeine Information¶

GET /api/version¶

Liefert Informationen über die Version des Duden Korrekturservers.

Request

GET /api/version HTTP/1.1
Content-Type: application/json
Accept: application/json

Response

Und die erwartete Antwort ist:

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{"Server version":"1.0","DPF version":"3.2.2"}

Prüfung und Silbentrennung¶

Prüft eines Text und/oder führt die Silbentrennung durch. Der zu prüfende Text wird zusammen mit etwaigen Parametern im Body des Requests im JSON-Format übergeben.

POST /api/check¶

Prüft einen Text.

Request

 POST /api/check HTTP/1.1
 Host: localhost:8099
 Content-Type: application/json
 Cache-Control: no-cache


 {
   "dictionaries": [
      "Tageszeitung",
      "jungblutt"
   ],

   "text-language": "de-DE",

   "property-sets": [
       "base",
       "Tageszeitung",
       "Kultur"
   ],

   "hyphenation": true,
   "spellchecking-level": 1,
   "correction-proposals": true,
   "single-word-mode": false,
   "message-language": "fr-LU",
   "message-level": 1,
   "text": "Das ist ein Endwurff f\u00fcr die Schnittstelle zum Duden-Server."
}

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
 "hyphenation-positions":[
   {"offset":15,"quality":0},
   {"offset":20,"quality":1}
 ],
 "check-positions":[
   {"offset":15,"length":6,"errorcode":4711,"type":"orth","severity":1,"proposals":["Entwurf","Entw\u00fcrfe"]},
  {"offset":22,"length":3,"errorcode":8221,"type":"orth","severity":1}
 ]
}

Das Ergebnis wird immer als JSON-Response geliefert, Content Negotiation findet nicht statt.

Parameter¶

Folgende Parameter können angegeben werden und werden zur Prüfung durchgereicht. Die Übergabe erfolgt als JSON-Array. Alle Parameter mit Ausnahme von text sind optional und werden mit Defaults besetzt.

Zusatzwörterbücher¶

Über den dictionaries Parameter kann eine Liste von Zusatzwörterbüchern übergeben werden, die bei der Verarbeitung verwendet werden sollen. Inhalt dieser Liste sind die Namen der zu verwendenden Wörterbücher.

"dictionaries": [
  "Tageszeitung",
  "Sport",
  "Ortsnamen im Bergischen Land"
]

Die angegebenen Wörterbücher müssen auf dem Server vorhanden sein. Die Pflege der Wörterbücher kann über das Web-Interface des Servers oder die Dictionary- API erfolgen.

Die Wörterbücher werden in der angegebenen Reihenfolge konsultiert. Für unbekannte Wörter ist dies ohne Belang. Bei der Silbentrennung und bei Negativeinträgen mit Korrekturvorschlägen kommt der zuerst gefundene Eintrag zum Tragen.

Voreinstellungen (Property Sets)¶

Mit dem Parameter property-sets können auf dem Server hinterlegte Voreinstellungen (Korrekturprofile, vgl. Serverseitige Einstellungen) selektiert werden.

"property-sets": [
  "base",
  "Tageszeitung",
  "Kultur"
]

Die Korrekturprofile werden in der angegebenen Reihenfolge ausgewertet, d. h. Einstellungen aus später angegebenen Profilen können Einstellungen aus früher angegebenen Profilen überschreiben.

Parameter für Prüfung und Trennung¶

Die folgenden Parameter steuern die Funktionen der Prüfung bzw. der Silbentrennung.

Name	Type	Default	Values
text	string	n/a	Der zu prüfende Text.
text-language	string	de-DE	de-DE, de-CH, de-AT, en, en-GB, en-US, fr, it, es, (RFC 5646)
spellchecking-level	int	1	0 = keine Prüfung, 1 = schnelle Rechtschreibprüfung, 2 = normale Rechtschreibprüfung, 3 = normale Rechtschreibprüfung und Grammatik
orthography-standard	string	duden	duden, conservative, progressive, extended, press
hyphenation	bool	false	Informationen zur Silbentrennung ausgeben
hyphenation-standard	string	combined	conservative, progressive, pronunciation, combined
hyphenation-in-stem	bool	true
hyphenation-unaest	bool	false
correction-proposals	bool	false
style-foreign	bool	false
style-old	bool	false
style-regional	bool	false
style-colloquial	bool	false
style-fillers	bool	false
style-offensive	bool	false
style-gender-inclusive	bool	false
single-word-mode	bool	false
glossary	bool	false	true = Glossareinträge auszeichen, false = Glossareinträge ignorieren
markup-mode	string	text	text, xml
message-language	string	de-DE	de-DE
message-level	int	0	0=keine, 1=kurz, 2=lang, 3=lang mit Beispiel

Kursive Parameter können auch über Korrekturprofile gesteuert bzw. je nach Einstellung durch Korrekturprofile überschrieben werden.

Der mögliche Prüfmodus (spellchecking-level) hängt von der gewählten Sprache ab. Für das Deutsche (Deutschland, Österreich und Schweiz) können alle Möglichkeiten verwendet werden, für die anderen Sprachen Englisch (en), en-GB (Englisch Großbritannien), en-US (Englisch USA) , fr (Französisch), it (Italienisch) oder es (Spanisch) steht nur eine normale Rechtschreibprüfung zur Verfügung.

Bemerkung

Wenn für die Sprachen en, en-GB, en-US, fr, it, oder es ein anderes spellchecking-level als 0 oder 2 angegeben wird, wird die normale Rechtschreibprüfung (spellchecking-level 2) verwendet.

Zusatzwörterbücher¶

Eine detaillierte Beschreibung von Zusatzwörterbüchern finden Sie im Abschnitt Zusatzwörterbücher.

Operationen auf Wörterbüchern¶

GET /api/dictionaries¶

Liefert Liste der verfügbaren Zusatzwörterbücher.

Request

GET /api/dictionaries HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

["0-Standard","Proposals","Tageszeitung"]

GET /api/dictionaries/{name}¶

Inhalt des Zusatzwörterbuchs name.

Request

GET /api/dictionaries/proposals HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{"alias":"Proposals",
 "learned-words":["Schmackofatz","Haii"],
 "exceptions":[{"word":"Abschluss","correction":["Ende"]}],
 "hyphenations":[]}

Bemerkung

Aus Gründen der Abwärtskompatibilität mit älteren Clients wird das Ergebnis im XML-Format geliefert, falls kein Accept-Header übergeben wird.

GET /api/dictionaries/{name}/timestamp¶

Liefert den Zeitpunkt der letzten Änderung des Zusatzwörterbuchs name.

Request

GET /api/dictionaries/proposals/timestamp HTTP/1.1
Accept: application/json

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{"last-modified":"2018-01-25T12:17:55+01:00"}

Das Ergebnis enthält den Zeitpunkt der letzten Änderung im ISO-8601 Format.

PUT /api/dictionaries/{name}¶

Speichert ein neues Wörterbuch unter dem Namen name. Der Inhalt des Dictionaries wird im Body des Requests im JSON-Format übergeben, das Format sollte im Content-Type-Header angegeben werden. Falls ein Wörterbuch name bereits bestehen sollte, wird der Inhalt des übertragenen Wörterbuchs diesem hinzugefügt.

Request

PUT /api/dictionaries/postman HTTP/1.1
Host: localhost:8099
Content-Type: application/json
Cache-Control: no-cache

{
  "description":"Geografische Begriffe",
  "learned-words":["fidunkeln"],
  "exceptions":[{"word":"Burma","correction":["Birma","Myanmar"]}],
  "hyphenations":[{"word":"fidunkeln","offsets":[{"offset":1,"quality":1},
                                         {"offset":4,"quality":1}]}]
}

Response

HTTP/1.1 201 Created

DELETE /api/dictionaries/{name}¶

Löscht das Wörterbuch mit dem Namen name. Das Wörterbuch name muss vorhanden sein, andernfalls wird ein Statuscode 404 geliefert.

Request

DELETE /api/dictionaries/postman HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

HTTP/1.1 204 No Content

Liefert 404 wenn nicht gefunden. Liefert 204 wenn erfolgreich.

Operationen auf Wörterbucheinträgen¶

API-Funktionen zum Zugriff (CRUD) für Zusatzwörterbücher

POST /api/dictionaries/{name}/accept¶

Erzeugt einen neuen Positiv-Eintrag im Dictionary name. Das Wort muss als JSON-konformer String im Request-Body übergeben werden.

Request

POST /api/dictionaries/postman/accept HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

"flabuzz"

Response

HTTP/1.1 201 Created

Alternativ kann im Request-Body ein JSON-Objekt folgender Form übergeben werden:

POST /api/dictionaries/0-Standard/accept HTTP/1.1
Content-Type: application/json

{"word": "flabuzz"}

GET /api/dictionaries/{name}/accept/{word}¶

Liefert einen vorhandenen Positiv-Eintrag für word im Dictionary name. Liefert 404 wenn nicht gefunden.

Request

GET /api/dictionaries/postman/accept/flab%C3%BCzz HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "word": "flabüzz"
}

DELETE /api/dictionaries/{name}/accept/{word}¶

Löscht den Positiv-Eintrag für word im Dictionary name.

Request

DELETE /api/dictionaries/postman/accept/flab%C3%BCzz HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

HTTP/1.1 204 No Content

Liefert 404 wenn nicht gefunden. Liefert 204 wenn erfolgreich.

POST /api/dictionaries/{name}/reject¶

Erzeugt einen neuen Negativ-Eintrag im Dictionary name. Das Wort und eine eventueller Ersetzungsvorschlag müssen im Request-Body übergeben werden.

Request

POST /api/dictionaries/postman/reject HTTP/1.1
Host: localhost:8099
Content-Type: application/json
Cache-Control: no-cache

{"word":"Abfahrt","correction":["Ende"]}

Response

HTTP/1.1 201 Created

GET /api/dictionaries/{name}/reject/{word}¶

Liefert einen vorhandenen Negativ-Eintrag für word im Dictionary name. Liefert 404 wenn nicht gefunden.

Request

GET /api/dictionaries/postman/reject/Abschluss HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

{
  "word": "Abschluss",
  "correction": [
     "Ende"
  ]
}

DELETE /api/dictionaries/{name}/reject/{word}¶: Löscht den Negativ-Eintrag für word im Dictionary name. Liefert 404 wenn nicht gefunden. Liefert 204 wenn erfolgreich.

POST /api/dictionaries/{name}/hyphenate¶

Erzeugt einen neuen Trenn-Eintrag im Dictionary name. Das Wort und seine Trennstellen müssen im Request-Body übergeben werden.

Request

POST /api/dictionaries/postman/hyphenate HTTP/1.1
Host: localhost:8099
Content-Type: application/json
Cache-Control: no-cache

{"word":"Abschlumps","offsets":[{"offset":1,"quality":2},
             {"offset":6,"quality":0}]}

Response

HTTP/1.1 201 Created

GET /api/dictionaries/{name}/hyphenate/{word}¶

Liefert einen vorhandenen Trenneintrag für word im Dictionary name. Liefert 404 wenn nicht gefunden.

Request

GET /api/dictionaries/postman/hyphenate/Abschlotz HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

 HTTP/1.1 200 OK
 Transfer-Encoding: chunked
 Content-Type: application/json

 {
  "word": "Abschlotz",
  "offsets": [
    {
        "offset": 1,
        "quality": 2
    },
    {
        "offset": 6,
        "quality": 0
    }
  ]
}

DELETE /api/dictionaries/{name}/hyphenate/{word}¶: Löscht den Trenn-Eintrag für word im Dictionary name.

Vorschläge¶

Anwender können Vorschläge zur Aufnahme von Wörtern in Zusatzwörterbücher machen. Diese Vorschläge werden zunächst in einem speziellen Zusatzwörterbuch gesammelt und können bei Akzeptanz in ein anderes Wörterbuch verschoben werden.

POST /api/propose/accept¶

Request

POST /api/propose/accept HTTP/1.1
Accept: application/json
Content-Type: application/json

Ein typischer Request-Body sieht so aus:

"fidunkeln"

Response

Und die erwartete Antwort ist:

HTTP/1.1 201 Created

Bemerkung

Das Vorschlagswörterbuch mit dem voreingestellten Namen Proposals kann wie jedes andere Wörterbuch mit den normalen Funktionen zum Hinzufügen von Einträgen befüllt werden. Daher ist die Verwendung dieser Funktion nicht mehr erforderlich und wird nur aus historischen Gründen unterstützt.

Korrekturprofile¶

Im DKS können unterschiedliche Korrekturprofile definiert werden, die für die Korrektur verwendet werden können.

GET /api/propset¶

Liefert die hinterlegten Korrekturprofile zurück.

Request

GET /api/propset HTTP/1.1
Host: localhost:8099
Cache-Control: no-cache

Response

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json

[
  {
    "id": 2,
    "name": "base",
    "description": "Default settings for all TinyMCE users",
    "checklevel": 3,
    "language": "de-DE",
    "orthstd": "progressive",
    "hyphstd": false,
    "stemhyph": false,
    "unaesthyph": false,
    "styforeign": true,
    "styold": true,
    "styregional": true,
    "stycolloquial": true,
    "styfiller": true,
    "enforce": true
  }
]

Bemerkung

Alle Felder (außer ‚id‘, ‚name‘, ‚description‘) sind optional. Wenn diese nicht mit übertragen werden, sind die Einstellungen nicht näher spezifiziert.

REST Protokoll¶

Allgemeine Information¶

Prüfung und Silbentrennung¶

Parameter¶

Zusatzwörterbücher¶

Voreinstellungen (Property Sets)¶

Parameter für Prüfung und Trennung¶

Zusatzwörterbücher¶

Operationen auf Wörterbüchern¶

Operationen auf Wörterbucheinträgen¶

Vorschläge¶

Korrekturprofile¶

Inhaltsverzeichnis

Vorheriges Thema

Nächstes Thema

Diese Seite