.. -*- fill-column: 78; -*- .. include:: general.txt ************** 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. .. note:: 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 ========================== .. http:get:: /api/version Liefert Informationen über die Version des Duden Korrekturservers. **Request** .. sourcecode:: http GET /api/version HTTP/1.1 Content-Type: application/json Accept: application/json **Response** Und die erwartete Antwort ist: .. sourcecode:: http 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. .. http:post:: /api/check Prüft einen Text. **Request** .. sourcecode:: http 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** .. sourcecode:: http 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. .. code-block:: json "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. :ref:`correction _profiles`) selektiert werden. .. code-block:: json "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. .. Nach Auflösung der Property-Sets gibt es folgende mögliche Parameter auf DPF-Seite (*kursive* Parameter entstehen durch Auflösung der property sets). 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. .. note:: 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. .. only:: internal ------------ Verarbeitung ------------ dictionaries werden auf PHP-Ebene verarbeitet und auf DPF dictionary Objekte abgebildet. property sets auf PHP-Ebene aufgelöst und in DPF Parameter settings überführt. Messages werden auf PHP-Ebene verarbeitet und ausgeliefert. Die folgenden DPF-Optionen haben keine direkte Entsprechung und werden wie angegeben behandelt: ``hyphenVowel`` ist obsolet. ``useSimlist`` wird nicht unterstüzt. ``sentenceMarkup`` immer, wenn spellchecking-level > 0. ``encoding`` ist immer UTF-8 ``cacheSize`` hard wired. Vernünftiger Wert wird vorgegeben. ``thesaurus`` Zugriff wird über eigenen API call realisiert. =================== Zusatzwörterbücher =================== Eine detaillierte Beschreibung von Zusatzwörterbüchern finden Sie im Abschnitt :ref:`dictionaries-main`. ----------------------------- Operationen auf Wörterbüchern ----------------------------- .. http:get:: /api/dictionaries Liefert Liste der verfügbaren Zusatzwörterbücher. **Request** .. sourcecode:: http GET /api/dictionaries HTTP/1.1 Accept: application/json **Response** .. sourcecode:: http HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: application/json ["0-Standard","Proposals","Tageszeitung"] .. http:get:: /api/dictionaries/{name} Inhalt des Zusatzwörterbuchs `name`. **Request** .. sourcecode:: http GET /api/dictionaries/proposals HTTP/1.1 Accept: application/json **Response** .. sourcecode:: http HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: application/json {"alias":"Proposals", "learned-words":["Schmackofatz","Haii"], "exceptions":[{"word":"Abschluss","correction":["Ende"]}], "hyphenations":[]} .. note:: Aus Gründen der Abwärtskompatibilität mit älteren Clients wird das Ergebnis im XML-Format geliefert, falls kein Accept-Header übergeben wird. .. http:get:: /api/dictionaries/{name}/timestamp Liefert den Zeitpunkt der letzten Änderung des Zusatzwörterbuchs `name`. **Request** .. sourcecode:: http GET /api/dictionaries/proposals/timestamp HTTP/1.1 Accept: application/json **Response** .. sourcecode:: http 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. .. http: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** .. sourcecode:: http 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** .. sourcecode:: http HTTP/1.1 201 Created .. http: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** .. sourcecode:: http DELETE /api/dictionaries/postman HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http 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 .. http: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** .. sourcecode:: http POST /api/dictionaries/postman/accept HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache "flabuzz" **Response** .. sourcecode:: http HTTP/1.1 201 Created Alternativ kann im Request-Body ein JSON-Objekt folgender Form übergeben werden: .. sourcecode:: http POST /api/dictionaries/0-Standard/accept HTTP/1.1 Content-Type: application/json {"word": "flabuzz"} .. http:get:: /api/dictionaries/{name}/accept/{word} Liefert einen vorhandenen Positiv-Eintrag für `word` im Dictionary `name`. Liefert 404 wenn nicht gefunden. **Request** .. sourcecode:: http GET /api/dictionaries/postman/accept/flab%C3%BCzz HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: application/json { "word": "flabüzz" } .. http:delete:: /api/dictionaries/{name}/accept/{word} Löscht den Positiv-Eintrag für `word` im Dictionary `name`. **Request** .. sourcecode:: http DELETE /api/dictionaries/postman/accept/flab%C3%BCzz HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http HTTP/1.1 204 No Content Liefert 404 wenn nicht gefunden. Liefert 204 wenn erfolgreich. .. http: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** .. sourcecode:: http POST /api/dictionaries/postman/reject HTTP/1.1 Host: localhost:8099 Content-Type: application/json Cache-Control: no-cache {"word":"Abfahrt","correction":["Ende"]} **Response** .. sourcecode:: http HTTP/1.1 201 Created .. http:get:: /api/dictionaries/{name}/reject/{word} Liefert einen vorhandenen Negativ-Eintrag für `word` im Dictionary `name`. Liefert 404 wenn nicht gefunden. **Request** .. sourcecode:: http GET /api/dictionaries/postman/reject/Abschluss HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: application/json { "word": "Abschluss", "correction": [ "Ende" ] } .. http: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. .. http: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** .. sourcecode:: http 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** .. sourcecode:: http HTTP/1.1 201 Created .. http:get:: /api/dictionaries/{name}/hyphenate/{word} Liefert einen vorhandenen Trenneintrag für `word` im Dictionary `name`. Liefert 404 wenn nicht gefunden. **Request** .. sourcecode:: http GET /api/dictionaries/postman/hyphenate/Abschlotz HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http HTTP/1.1 200 OK Transfer-Encoding: chunked Content-Type: application/json { "word": "Abschlotz", "offsets": [ { "offset": 1, "quality": 2 }, { "offset": 6, "quality": 0 } ] } .. http: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. .. http:post:: /api/propose/accept **Request** .. sourcecode:: http POST /api/propose/accept HTTP/1.1 Accept: application/json Content-Type: application/json Ein typischer Request-Body sieht so aus: .. code-block:: json "fidunkeln" **Response** Und die erwartete Antwort ist: .. sourcecode:: http HTTP/1.1 201 Created .. note:: 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. .. http:get:: /api/propset Liefert die hinterlegten Korrekturprofile zurück. **Request** .. sourcecode:: http GET /api/propset HTTP/1.1 Host: localhost:8099 Cache-Control: no-cache **Response** .. sourcecode:: http 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 } ] .. note:: Alle Felder (außer 'id', 'name', 'description') sind optional. Wenn diese nicht mit übertragen werden, sind die Einstellungen nicht näher spezifiziert.