Der DissChain WDDS Translator ist ein Webdienst, der einen älteren WDDS 2.1-REST in eine Anforderung übersetzt, die an die RENOV-API gesendet wird, wobei die Reihenfolge der Parameter unabhängig ist. Dies bedeutet, dass diese Parameter keine bestimmte Reihenfolge einhalten müssen.
Die RENOV-API gibt eine Datei als Anhang (Daten und Metadaten aus einem einzelnen Datensatz) im JSON-Stat 2.0-Format an den WDDS Translator zurück. Letzterer gibt den Inhalt der Datei als JSON-Antwort ohne Inhaltstransformation an den Anforderer zurück.
Der Webdienst:
stellt Daten im JSON-stat 2.0-Format bereit;
unterstützt nur das REST-Protokoll (Representation State Transfer);
liefert Antworten in englischer, französischer und deutscher Sprache.
WDDS Translator ersetzt den alten WDDS 2.1-Webdienst und ermöglicht einen reibungslosen Übergang der Estat.B4-Visualisierungsanwendungen.
Am Ende werden die Funktionen des WDDS Translators in den neuen RENOV-API-Endpunkt integriert und transparent durch diesen ersetzt.
Die Struktur der REST-Anfrage
Die Struktur zum Erstellen der REST-Anforderung ist eine URL: {host_url}/{service}/{version}/{response_type}/{datasetCode}?{format}&{lang}&{filters}
URL-Teil | Beispiel | Kommentar |
|---|---|---|
Fester Teil (fixed part) | ||
{host_url}/ | Fester Teil der Anfrage im Zusammenhang mit unserer Website | |
{service}/ | statistics/ | Fester Teil der Anfrage im Zusammenhang mit dem Service |
{version}/ | 1.0/ | Fester Teil der Anfrage im Zusammenhang mit der Version des Services |
Dynamischer Teil (dynamic part) | ||
{response_type}/ | data/ | Derzeit werden nur statistische Daten zurückgegeben |
{datasetCode} | t2020_10 | Eindeutige Code-ID des abgefragten Datenprodukts (entweder ein Datensatz oder eine vordefinierte Extraktion) |
?{format} | ?format=JSON | Optionaler Parameter |
&{lang} | &lang=DE | Optionaler Parameter |
&{filters} | &time=2019 | Optionaler Parameter |
Die in der REST-Anforderung definierten Parameter
Die Filter-Parameter
Die in der URL definierten Filterparameter sind optional. Jede im Datenprodukt vorhandene Dimension kann als Filterparameter verwendet werden.
Filter beginnen nach dem Fragezeichen ("?") In der URL. Sie werden durch ein kaufmännisches Und ("&") getrennt, wenn viele Filter vorhanden sind.
Die Struktur eines Filterparameters: <DIMENSION_CODE> = <WERT>
DIMENSION_CODE: Der Code der Dimension, die zum Filtern von Daten verwendet wird
der Dimensionscode muss im Datenprodukt vorhanden sein
es ist nicht erforderlich, dass die Reihenfolge der Filter der Reihenfolge der Abmessungen im Datenprodukt entspricht
VALUE: Der Wert des Filters ist die Position in der Dimension, d. H.
time=2019
geo=DE
DIMENSION_CODE und VALUE unterscheiden nicht zwischen Groß- und Kleinschreibung. Sie können in der URL-Anforderung in Klein- oder Großbuchstaben geschrieben werden.
Der Zeit-Parameter
In der URL werden sowohl die Parameter "time" als auch "time_period" akzeptiert. Beide adressieren die Dimension TIME_PERIOD.
Definiert sind andere Zeitparameter, die verwendet werden können:
untilTimePeriod – der spezifische TIME_PERIOD-Wert zum Filtern der zurückgegebenen Datei bis zu diesem Wert
sinceTimePeriod – der spezifische TIME_PERIOD-Wert zum Filtern der zurückgegebenen Datei seit diesem Wert
lastTimePeriod – ein numerischer Wert, der herunterzählt, bis die Dimensionswerte TIME_PERIOD in der zurückgegebenen Datei enthalten sind
Die Verwendung von mehr als einem Zeitparameter in derselben Abfrage wird nicht akzeptiert.
Die einzige Ausnahme ist die Verwendung von SinceTimePeriod und tillTimePeriod. Dadurch wird die gefilterte Datei basierend auf den spezifischen Werten für die beiden Zeitparameter zurückgegeben.
Die Format- und Sprachparameter
Der einzig mögliche Wert des Format Parameters ist "JSON".
Der Sprachparameter kann nur drei Werte haben: "EN", "FR" und "DE". Falls der Parameter nicht angegeben wird, wird der Standardwert „EN“ verwendet.
Bei ungültigen Abfragen werden Fehlermeldungen zurückgegeben
Fehlercode | HTTP-Status | Beschreibung |
|---|---|---|
Client-Fehler | ||
100 Kein Ergebnis gefunden | 400 Ungültige Anfrage | Das Ergebnis der Abfrage ist leer. |
100 Kein Ergebnis gefunden | 404 Nicht gefunden | Die angeforderte Ressource ist nicht verfügbar. |
110 Nicht autorisiert | 401 Nicht autorisiert | Zur Verwendung, wenn eine Authentifizierung erforderlich ist, diese jedoch fehlgeschlagen ist oder noch nicht bereitgestellt wurde. ECAS-Fehler können sein:
|
140 Syntax-Fehler | 400 Ungültige Anfrage | Die Abfrage ist ungültig. |
140 Syntax-Fehler | 404 Nicht gefunden | Die angeforderte Ressource ist nicht Teil der unterstützten Methoden. Nicht unterstützte Ressourcen:
|
150 Semantischer Fehler | 400 Ungültige Anfrage | Die Anforderung ist syntaktisch korrekt, schlägt jedoch einer semantische Validierung und Validierung gegen Geschäftsregeln fehl. |
Serverfehler | ||
500 Interner Serverfehler | 401 Nicht autorisiert | Die angeforderte Ressource ist vorhanden, aber derzeit nicht verfügbar. |
500 Interner Serverfehler | 500 Interner Serverfehler | Der Webservice sollte diesen Fehlercode zurückgeben, wenn keiner der anderen Fehlercodes den Grund für das Versagen des Dienstes, eine aussagekräftige Antwort zu liefern, besser beschreibt. Wird auch verwendet, wenn die Anforderung die xsd-Definition nicht berücksichtigt. |
Asynchrone Antwort bei großen Extraktionen
Beim Empfang einer Anforderung vom WDDS Translator kann die API bestimmen, ob die Antwort synchron oder asynchron erfolgen kann.
Im Falle einer asynchronen Antwort gibt der WDDS Translator die folgende JSON-Antwort zurück:
{"warning":{"status":413, "label":"ASYNCHRONOUS_RESPONSE. Your request will be treated asynchronously. Please try again later."}}
WDDS benachrichtigt den Benutzer nicht, wenn die Datei fertig ist. Die Anforderung muss erneut gestellt werden, um den Status zu überprüfen.