Die Wiwald API orientiert sich an REST-Prinzipien und bietet im Moment zwei Endpunkte an, mit denen man Datensätze erzeugen und herunterladen kann.

Zugriffsschutz

Der Zugriff auf die gesamte API wird mit Hilfe der Basic Auth Methode geschützt. Der Username entspricht dabei der E-Mail-Adresse des Wiwald-Accounts, das Passwort entspricht dem API-Key der sich im Profil des Accounts findet.

Hinweis: Der Zugriff auf unsere API ist auch bei kostenfreien Datensätzen nur durch die Nutzung eines API Keys möglich. Diesen erhalten Sie kostenlos, wenn Sie sie auf unserer Plattform registrieren.

Grundlagen

Ein Datensatz bei wiwald ist immer definiert durch die folgenden drei Werte:

  • eine Datensatz-ID
  • eine Versions-ID
  • eine Formatspezifikation

Aufgrund der vielen möglichen Kombinationen dieser drei Parameter wird der Zugriff auf eine konkrete Variante asynchron zur Verfügung gestellt. D.h. dass erst ein Aufruf an den jobs Endpunkt erfolgen muss, der die Erzeugung der konkreten Ausgabe auslöst. Erst wenn diese durchgeführt wurde (status=finished), kann der Datensatz über den datasets Endpunkt heruntergeladen werden.

 

Der jobs Endpunkt

Der jobs-Endpunkt stellt zwei Methoden bereit:

POST /jobs

Der ContentType muss „application/json“ sein, der Body muss einer vollständigen JSON-Spezifikation entsprechen. eine derartige Spezifikation kann in der Detailansicht des Shops bei jedem Datensatz in Ihrer Bibliothek direkt heruntergeladen werden.

Der Rückgabewert entspricht wieder einer JSON-Datei, die wie folgt aussehen kann:

{
  "id":"ad8b60c28e970b34a731fbff8cfb1e4d",
  "type":"json",
  "status":"init",
  "spec":{...},
  "created_at":"2018-05-06T08:06:13.000Z"
}

Die Methode verhält sich idempotent, d.h. ein mehrfach gleicher Aufruf erzeugt keine weiteren Jobs sondern gibt immer die gleiche Job-ID zurück.
Erst wenn der Status auf finished steht, kann der Datensatz über den Datasets-Endpunkt heruntergeladen werden.

GET /jobs/<id>

Als <id> muss die ID aus einem zuvor durchgeführten POST-Aufruf verwendet werden. Der Rückgabewert entspricht dem Wert des POST-Aufrufs.

 

Der datasets Endpunkt

GET /datasets?job_id=<id>

Um einen erzeugten Datensatz herunterzuladen, muss als <id> wieder die ID eines Jobs (siehe oben) gesendet werden. Als Rückgabewert erhält man dann die jeweilige Ausgabe mit dem Content-Typ, der dem gewählten Format entspricht..

 

Vollständiges Beispiel in Python

 

import requests
import json
import time

ww_url = "https://api.wiwald.com/"
ww_user = "<account-mail-address>"
ww_api_key = "<account-api-key>"

# replace the spec with any spec downloaded from the shop.
spec = {
    "type":"csv",
    "filters":{"ignore_columns":[]},
    "spec":{
        "delimiter":";",
        "delimiter_escape":"",
        "quote":"\"",
        "quote_escape":"\"",
        "line_delimiter":"\n",
        "line_delimiter_escape":"\n",
        "quote_mode":"smart",
        "encoding":"utf-8",
        "header":True,
        "timestamp_format":"timestamp"},

   "dataset_id":"ww.example-dataset",
   "version_id":"20180425_144425_966577"
}

result = None
while True:
    try:
        job_request = requests.post(
            ww_url + "jobs/", 
            json.dumps(spec), 
            headers={'content-type': 'application/json'}, 
            auth=(ww_user, ww_api_key))
        job_result = json.loads(job_request.content.decode("utf-8"))
        if job_result["status"] == "finished":
            result = requests.get(
                ww_url + "datasets/" + job_result["id"], 
                auth=(ww_user, ww_api_key)
            )
            break
        elif job_result["status"] != "failed":
            # retry every 5 seconds until the job is finished or failed
            time.sleep(5) 
        else:
            print("job failed")
            break
    except Exception as e:
        print(e)
        break


if result != None:
    print(result.content)

1 Kommentar

Newsletter #2: Neue Features in der Shop-Preview | wiwald · 28. Juni 2018 um 10:47

[…] einen Zugang zu unserer Preview besitzen. Eine Dokumentation dazu finden Sie unter folgendem Link auf unserer Website. Die API bietet im Wesentlichen die gleiche Möglichkeit auf Datensätze zuzugreifen wie die […]

Schreibe einen Kommentar zu Newsletter #2: Neue Features in der Shop-Preview | wiwald Antworten abbrechen

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.