Web REST-API

Die öffentliche REST-API ist unter der URL https://api.sharedmobility.ai/ abrufbar. Standardmäßig wird ein Aufruf der Root-URI auf die jeweils aktuellste API-Version umgeleitet. Die aktuellste Version ist v1 (Stand: Oktober 2019). Im Hintergrund verwendet diese Schnittstelle die im smai-public-models Bucket veröffentlichen Modelle.

Die Web REST-API bietet zwei grundsätzliche Funktionen an:

  • /models – Abfrage und Metadaten der zur Verfügung stehenden TensorFlow-Modelle. So können die einzelnen Layer eines Modells schnell betrachtet werden oder die für jede Station verfügbaren Modelle aufgelistet werden.
  • /predict – Anfordern einer Vorhersage für eine bestimmte Station. Sämtliche Eingabedaten für das Modell werden hierbei automatisch bereitgestellt und müssen nicht über weitere Parameter übergeben werden.

Jeder Aufruf muss über HTTP/1.1 oder HTTP/2 erfolgen. Alle API-Methoden erfordern zwingend eine verschlüsselte TLS-Verbindung über HTTPS. Es wird nur TLS 1.2 oder neuer unterstützt, ältere Protokollvarianten sind nicht aktiviert. Für clientseitige Web-Applikationen werden folgende HTTP-Header ausgeliefert, die das Cross-Origin-Verhalten in Browsern steuern:

  • Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

In der Web-Demoapplikation kann die Verwendung der REST-Schnittstelle genauer betrachtet werden werden.

Referenz – API-Version v1

  • /models/:service/:station
    Listet alle verfügbaren Modelle für die jeweilige Station auf.
  • /models/:service/:station/:model/summary
    Gibt eine Zusammenfassung über das jeweilige Modell zurück. Hierfür wird die Methode tf.LayersModel.summary im Hintergrund verwenden. Über den Query-Parameter format kann optional von einer JSON-Ausgabe auf eine reine Textausgabe umgestellt werden.
  • /predict/:service/:station
    Liefert eine aktuelle Vorhersage für die angegebene Station. Es müssen keine speziellen Eingabevariablen übergeben werden. Die Ausgabe enthält immer Vorhersagen für die nächsten 60 Minuten, je in 15-minütigen Intervallen. Standardmäßig wird immer das Modell „best“ für die Vorhersage ausgewählt, über den Query-Parameter model kann aber auch ein beliebiges Modell ausgewählt werden.

Beispiele für API-Aufrufe