data2check-Dokumentation – Verwendung der API

1. Zweck

Die mit dem kostenlosen Dienst data2check möglichen Prüfungen lassen sich auch ohne die Web-Oberfläche durchführen und können so in andere bestehende Dienste, wie Content Management Systeme, integriert werden. Zu diesem Zweck wird von data2check eine einfache REST-API angeboten, die eine Prüfung von Dokumenten ermöglicht.

2. Ein API-Token erstellen

Um die REST-API nutzen zu können, muss zunächst ein sogenanntes "API-Token" erstellt werden. Dazu wird in der Benutzerverwaltung (auf der rechten Seite des Hauptmenüs) der Punkt »API-Tokens« ausgewählt (siehe Abb. 1, orangener Kreis).

Benutzerverwaltung von data2check - API-Tokens

Abbildung 1: Die Benutzerverwaltung von data2check - API-Tokens

Nun erscheint die API-Token-Verwaltung. Klicken Sie auf den grünen »API-Token erzeugen«-Button (siehe Abb. 2), um sich ein Token zu erstellen.

Verwaltung von API-Tokens - API-Token erzeugen

Abbildung 2: Verwaltung von API-Tokens - API-Token erzeugen

Auf der folgenden Seite können API-Tokens angezeigt, erneuert (grüner »API-Token auffrischen«-Button) und gelöscht (roter »API-Token löschen«-Button) werden. Pro Nutzer ist jeweils nur ein API-Token gleichzeitig aktiv, dieses kann für alle verfügbaren Prüfkonfigurationen genutzt werden (siehe Abb. 3).

Das aktuelle API-Token

Abbildung 3: Das aktuelle API-Token (beispielhafte Darstellung)

ACHTUNG: Ein API-Token hat grundsätzlich nur eine beschränkte Laufzeit und muss nach Ablauf erneuert werden. Normalerweise beträgt die Standard-Laufzeit einen Monat.

3. Ein Dokument prüfen

Die API bietet die Möglichkeit, Word- und InDesign-Dokumente zu prüfen. Das Ergebnis von jedem Aufruf ist genau ein Ergebnisdokument. Um die Erstellung der zu benötigten URLs zu vereinfachen, bietet die API-Token-Verwaltung eine Übersicht über alle verfügbaren Prüfkonfigurationen und die dazu passenden REST-URLs, wobei der passende API-Token bereits in die URL eingesetzt ist. Nach Auswahl des gewünschten Ergebnis-Typs kann die URL damit einfach kopiert und in das eigene System eingefügt werden.

Die (gegebenenfalls) verfügbaren Prüfkonfigurationen sind grau hinterlegt. Mit Klick auf eine der vorhandenen Konfigurationen, erscheinen folgende Angaben: der für die jeweilige Konfiguration hinterlegte Beschreibungstext (Beschreibung), eine Dropdown-Liste der möglichen Typen von Ergebnisdokumenten (Typ) sowie die zur gewählten Ausgabe passende REST-URL (siehe Abb. 4).

Angaben zur ausgewählten Prüfkonfiguration

Abbildung 4: Die Angaben zur ausgewählten Prüfkonfiguration (beispielhafte Darstellung)

Je nachdem, welches Ergebnisdokument gewünscht ist (die kommentierte Version des Dokuments, die XML-Version des Dokuments, der Prüfbericht im XML-Format oder der formatierte HTML-Prüfbericht), muss dieses in der Dropdown-Liste bei »Typ« ausgewählt werden (siehe Abb. 5).

Auswahl des gewünschten Ausgabeformats

Abbildung 5: Auswahl des gewünschten Ausgabeformats

Weitere Informationen zu den nach einer Prüfung verfügbaren Ergebnisdokumenten finden Sie unter Ein Word-Dokument prüfen - 3.2 Die Ausgabe-Dokumente für Word, unter Ein InDesign-Dokument prüfen - 3.2 Die Ausgabe-Dokumente sowie unter Der InDesign-zu-EPUB-Check - 2.2 Die Ausgabe-Dokumente für InDesign.

Um eine Prüfung durchzuführen wird ein POST-Request im Format multipart/form-data an die entsprechende URL geschickt. Die zu prüfende Datei muss als Parameter mit dem Namen file angehängt werden. Die Verarbeitung erfolgt synchron, das heißt der Request läuft so lange, bis die Prüfung abgeschlossen ist und schickt dann das gewünschte Ausgabe-Format als Ergebnisdokument zurück. Je nach Belastung des data2check-Dienstes kann dies einige Sekunden dauern.

Beispiel: Mit curl könnte die Prüfung eines Word-Dokuments so durchgeführt werden:

curl -X POST -o ergebnis.docx -F file=@beispiel.docx "http://service.data2check.de/api/doc/docx?wfid=KONFIGURATIONS-ID&tokenid=TOKEN"

4. Nutzungsbeschränkungen

Pro Nutzer kann nur eine Prüfung gleichzeitig durchgeführt werden. Dies ist bei der Integration in bestehende Dienste zu beachten. Bei übermäßiger Nutzung behält sich data2check vor, Nutzungskontingente einzuführen. Sonderkonditionen, wie zum Beispiel eine verlängerte Gültigkeitsdauer von API-Tokens, sind in Einzelfällen nach Absprache möglich. Unsere Kontaktdaten finden Sie unter Kontakt.

Copyright © 2017 data2check, all rights reserved

AGBs | Impressum | Datenschutzerklärung