Abkürzungen und Begriffsdefinitionen

• API – Application Programming Interface. Programmteil, der von einem Softwaresystem anderen Programmen zur Anbindung an das System zur Verfügung gestellt wird.

• API-Consumer – Nutzer der API ausserhalb der Q Point-Applikation, welche die Schnittstelle implementiert.

• Authentifizierung – Ist der Nachweis (Verifizierung) einer behaupteten Eigenschaft einer Entität, die beispielsweise ein Mensch oder ein System sein kann, und die dabei durch ihren Beitrag ihre Authentisierung durchführt.

• Autorisierung - Das initiale Zuweisen und das wiederholte Überprüfen von Zugriffsrechten.

• Fremdsystem – System, welches die API anspricht und dadurch den Webservice nutzt. Gleichbedeutend mit API-Consumer.

• REST - Auf dem http-Übertragungsprotokoll basierender Architekturstil für Anwendungsschnittstellen von verteilten Systeme. Informationen werden dazu ressourcenorientiert strukturiert und sind über eine eindeutige URL adressierbar.

• JSON – JavaScript Object Notation. Kompaktes Datenformat für den Datenaustausch zwischen Anwendungen.

• HTTP - Hypertext Transfer Protocol. Zustandsloses Protokoll zur Übertragung von Daten über das Internet.

• HTTPS - HyperText Transfer Protocol Secure. Erweitertes HTTP Protokoll für die abhörsichere Übertragung von Daten über das Internet.

• Service – Abgekürzte Form für „Webservice" oder „Webdienst". Anwendungsschnittstelle zur Verbindung von Systemen, insbesondere für die direkte Maschine-zu-Maschine-Interaktion. Service ist ein synonym für API.

• SSL / TLS - Secure Sockets Layer, die alte Bezeichnung für Transport Layer Security, ein Netzwerkprotokoll zur sicheren Übertragung von Daten über das Internet.

• URL - Uniform Resource Identifier. Zeichenfolge zur eindeutigen Adressierung und Lokalisierung einer Ressource.

• UTC - Coordinated Universal Time. Referenzzeit zur Definition der Zeitzonen. Auch „Zulu"-Time genannt.

REST Basics

Das Design der API's basiert auf dem REST (Representational State Transfer) Architekturstil. Daraus ergeben sich die nachfolgenden Grundsätze:

• HTTP Übertragungsprotokoll – Die Kommunikation mit der API basiert auf dem HTTP-Übertragungsprotokoll.

• Standard HTTP-Methoden – Zur Interaktion mit der API werden ausschliesslich die Standard HTTP-Methoden: GET, POST, PUT, PATCH und DELETE verwendet. Hierbei handelt es sich um ein Set von generischen Befehlen, die als Verben (HTTP-Verbs) bezeichnet werden.

• Ressourcenorientierte Informationsstruktur – Im Gegensatz zu alternativen Designansätzen, bei denen eher Vorgänge oder Befehle als Schnittstellen-Methoden abgebildet werden (beispielsweise RPC), besitzen REST-Schnittstellen eine ressourcenorientierte Struktur.

• URL – Jede der vorgenannten Ressourcen besitzt eine eindeutige URL, über welche sich die Ressource adressieren und damit auch ansprechen lässt.

HTTP Version

Die API unterstützt ausschliesslich Aufrufe der Version HTTP/1.1

JSON als Datenformat

Die API nutzt das Datenformat JSON für den Informationsaustausch. Dies gilt sowohl für den Nachrichteninhalt bei Methodenaufrufen als auch für die zurückgelieferten Ressourcen, inklusive Fehlerinformationen.
Beispiel für das Abholen von Daten:

GET https://asphaltag.q-plant.com/apiinfos

Antwort

Standard HTTP-Methoden (Verbs)

Für den Zugriff auf die Ressourcen stehen ausschliesslich die nachfolgend aufgeführten Standard HTTP-Methoden zur Verfügung:

Für alle anderen als die vorangehend aufgeführten Methoden, antwortet der Service mit einem HTTP-Statuscode: 501 „Not Implemented"

Sicherung der Übertragung mittels HTTPS

Sämtliche Kommunikation mit dem Service erfolgt über das HTTPS-Protokoll. Dies gilt sowohl für API-Aufrufe von Konsumenten als auch für die Callback-Aufrufe des Q Point-Webservice an die Konsumenten. Durch die Verwendung des HTTPS-Protokolls werden zwei Dinge sichergestellt:

• Der Aufrufer ist in der Lage, den Kommunikationspartner auf Basis eines Zertifikats zu authentifizieren. Damit wird sichergestellt, dass dieser auch wirklich mit dem gewünschten Empfänger kommuniziert.

• Die gesamte Datenübertragung ist in beiden Kommunikationsrichtungen mittels SSL bzw. TLS verschlüsselt und damit abhörsicher und manipulationsgeschützt.

API-Aufrufe mit HTTP anstelle von HTTPS, beantwortet der Service mit einem HTTP-Fehlercode: 403 „Forbidden"

Authentifizierung gegenüber dem Service

Der Zugriff auf die API ist ausschliesslich autorisierten Konsumenten vorbehalten. Die Authentifizierung erfolgt mithilfe eines „Authorization Access Key", der bei allen Aufrufen in Form eines HTTP Authorization-Headers mit angegeben wird.

Authorization: apikey eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwh8.......

Fehlt der Key oder ist er falsch, antwortet der Service mit einem HTTP-Fehlercode: 401 „Unauthorized"

Beschaffung eines Zugangscodes

Der Access-Key wird von Q Point auf Anfrage an autorisierte Konsumenten ausgegeben. Fremdsysteme, welche den Webservice nutzen möchten, melden sich beim Q Point Support.

Request Throttling

Eine unsachgemässe Verwendung des Dienstes kann dessen Stabilität und Verfügbarkeit nachhaltig beeinflussen. So wird beispielsweise eine anhaltend hohe Anzahl von Abfragen, die Antwortzeiten erhöhen oder den Dienst gar ganz ausser Betrieb setzen. Um solchen Missbrauch zu verhindern und die Stabilität des Dienstes sicherzustellen, ist die Anzahl der zur Verfügung stehenden API-Aufrufe innerhalb eines vorgegebenen Zeitraums limitiert. Der entsprechende Grenzwert ist applikationsbezogen. Unterschiedliche Konsumenten werden damit einzeln betrachtet und besitzen jeweils eine eigene Anzahl von verfügbaren API-Calls.
Der Grenzwert beschränkt die Anzahl der Aufrufe pro Stunde. Dieser ist jedoch ist so hoch angesetzt, dass er bei einer sachgemässen Verwendung ausser Acht gelassen werden kann.

Spracheinstellung und Lokalisierung

In der aktuellen Version der API gibt es keine sprachabhängigen Ressourcen. Die meisten Informationen liegen in derjenigen Sprache vor, wie sie von der Mischanlage oder den Fremdsystemen erfasst wurden. Eine Lokalisierung ist hier nicht notwendig. Mit zunehmender Verbreitung des Service wird dies zukünftig jedoch sicherlich zu einer Anforderung. Um spätere Anpassungen zu vermeiden, wird die hierzu notwendige Basisfunktionalität bereits jetzt in die API eingebaut.
Zur Festlegung der vom Konsumenten geforderten Sprache bzw. Lokalisierung wird der Accept-Language HTTP-Header verwendet. Dieser muss bei jedem Aufruf mit angegeben werden. Die Angabe erfolgt mithilfe des Microsoft Language Code (Bsp: ‚de-DE' oder ‚en-GB'):

Accept-Language: de-DE

Prinzip des “Tolerant Reader”

Nutzer des API sind angehalten, das Prinzip des “Tolerant Reader“ (Siehe: https://martinfowler.com/bliki/TolerantReader.html) einzuhalten. Um Mehraufwand durch neue API Versionen zu minimieren und Inkompatibilitäten zu vermeiden, sollen Clients so tolerant wie möglich Informationen von dem API lesen. Hierzu werden insbesondere zusätzliche Felder, welche neu hinzukommen sind und der Client deshalb nicht kennt, ignoriert.

Status und Error Codes

Sämtliche API-Operationen liefern einen Standard HTTP-Statuscode zurück. Die Bedeutung der einzelnen Codes ist durch die „HTTP/1.1 Status Code Definitions" festgelegt. Im Wesentlichen handelt es sich um die folgenden Codes:

Rückgabewerte

Fehler-Entität

Im Falle eines Fehlers mit einem Status-Code 400 oder 500, liefert der Service zusätzlich eine Fehlerinformation in Form eines Response Body. Es handelt sich um eine geordnete Liste von Fehlern, bestehend aus den nachfolgenden Attributen:

Beispiel:

Error Response Body

Hinweise zur PATCH-Methode

Eine PATCH-Methode führt eine partielle Aktualisierung einer bestehenden Ressource durch. Der Client adressiert die Ressource hierbei mithilfe der ID in der URI. PATCH Methoden arbeiten nach dem Prinzip des “JSON-Patch“ (RFC 6902). Der Request-Body spezifizierte hierbei einen Satz von anzuwendenden Operationen an.  

Folgende Operationen stehen grundsätzlich zur Verfügung.

• add - Fügt einem Objekt oder Array einen Wert hinzu.

• remove - Entfernt einen Wert aus einem Objekt oder Array.

• replace - Ersetzt einen Wert

Die Spezifikation des jeweiligen Endpunkts definiert, welche Operationen auf den einzelnen Feldern zulässig sind.

Response Body

Als Antwort liefert der Endpunkt sowohl die Original-Entität vor dem Patch, als auch das entsprechende Ergebnis des Patch zurück.

Bedeutung und Verwendung der Felder id, identifier und name

Alle für die Synchronisierung vorgesehenen Ressourcen sind einheitlich mit den Feldern id, identifier und name ausgerüstet. Die Verwendung dieser Felder unterliegt den folgenden Grundsätzen:

• id– Hierbei handelt es sich um den Schlüsselwert der Ressource. Er wird genutzt um die Ressource über die Systemgrenzen hinweg d.h. für alle beteiligten Systeme einheitlich zu identifizieren. Die 'id' ist für den Endanwender unsichtbar, wird bei der Erzeugung der Ressource angelegt und anschliessend nicht mehr geändert. Für die id's werden Global Unique Identifier (GUID)-Werte verwendet. Das ID-Feld besitzt den Datentyp ‚String' mit einer Länge von genau 36 Zeichen. Vier Zeichen sind für trennende Bindestriche zu verwenden, und die übrigen 32 Zeichen für fünf Hexadezimalzahlen im GUID-Muster 8-4-4-4-12.

• identifier – Hierbei handelt es sich um die Kennung der Ressource. Die Kennung ist für den Endanwender sichtbar und dient diesem zur Selektion der Ressource. Innerhalb eines bestimmten Ressourcentyps sollte die Kennung eindeutig sein. Das Identifier-Feld besitzt den Datentyp ‚String'.

• name – Hierbei handelt es sich um eine frei formulierbare Bezeichnung der Ressource. Der Name wird dem Endanwender neben der Kennung als zusätzliche Information dargestellt. Im Gegensatz zum Identifier muss der Name nicht eindeutig sein. Das Name-Feld besitzt den Datentyp ‚String'.

Systemweit eindeutige Identifizierung der Datenobjekte

Für die gemeinsame Verwendung von Ressourcen ist es notwendig, die Objekte über die jeweiligen Systemgrenzen hinweg eindeutig zu identifizieren. Das angewendete Verfahren basiert auf den folgenden Grundsätzen und Regeln:

• Zur Identifizierung der Datenobjekte wird ein GUID-Wert verwendet. Dasjenige System, welches das Objekt anlegt, erzeugt den eindeutigen Schlüsselwert. Dieser Schlüsselwert bleibt während der Lebensdauer des Datenobjekts unverändert!

• Die Übermittlung des Schlüsselwertes erfolgt immer im Feld mit der Bezeichnung ‚id'.

• Bei der Übermittlung des neuen Datensatzes an das gegenüberliegende System, speichert dieses den Schlüsselwert und benutzt diese bei allen nachfolgenden Mitteilungen.

• Der Schlüsselwert ‚id' ist innerhalb des Q Point-Systems für den Endanwender nicht sichtbar.

Formatierung von HTTP-Parameter

Für die Verwendung der HTTP-Parameter gelten die folgenden Grundsätze:

• Sämtliche Parameterangaben sind nicht case sensitive.

• Mehrere aufeinanderfolgende Wörter sollen durch ein Leerzeichen getrennt werden. Das Leerzeichen wir mit dem Steuerzeichen ‚%20' angegeben. Beispiel: „Hot-Asphalt%20GmbH".

• Wildcards und boolsche Logik werden nicht unterstützt (Bsp: *, ?, AND, and OR)

Date Time Werte

Sofern nicht anderslautend festgelegt, werden Zeit- und Datumsangaben gemäss ISO8601 formatiert. Entsprechende Informationen hierzu finden sich unter W3C-Note Date and Time Formats oder Wikipedia-ISO8601.

• Format:    YYYY-MM-DDTHH:MM:SS[TimeZone]

• Beispiel:   2015-03-12T13:24:00Z

Wie durch die Norm vorgegeben, wird der Bezug zur Zeitzone durch Angabe einer Abweichung zu UTC angegeben. `Z` steht hierbei für `Zulu`-Time was gleichbedeutend ist mit UTC. Angaben zur Zeitzone sind in Form eines Identifiers spezifiziert. Eine Auflistung der verfügbaren Identifier findet sich in der IANA Time Zone Database, oder in der Wikipedia List of tz database time zones.

Die API erwartet und liefert sämtliche Datums- und Zeitwerte ohne Zeitzone und verstehen sich als `local time` bzw. die eingestellte Zeitzone der jeweiligen Q-Plant Kundeninstanz.

GEO Positionen

Geo-Koordinaten dienen dazu, die geografische Position beispielsweise einer Mischanlage oder einer Baustelle zu spezifizieren. Pro Positionsangabe wird ein Wert für den Breitengrad (Latitude) gefolgt vom Längengrad (Longitude) angegeben, ausgehend vom Bezugssystem WGS 84. Die beiden Koordinatenwerte sind im DDD (Grad und Grad dezimale) Format notiert und durch ein Semikolon getrennt.

Format: „Breitengrad (latitude); Längengrad (longitude)"

Die nachfolgende Positionsangabe spezifiziert beispielsweise die geografische Lage des Kölner Doms:

GEO Fences

Geo-Fences werden genutzt, um geografische Bereiche wie das Werksgelände eines Mischwerks oder ein Baustellengelände abzugrenzen. Damit lassen sich in der Folge Ereignisse wie etwas “Transportfahrzeug verlässt das Werksgelände” oder Stati wie “Baugerät befindet sich auf der Baustelle“ automatisiert ableiten.

Geofences werden in Form von “Polygon” oder “MultiPolygon” im Geo-JSON Format (https://www.rfc-editor.org/rfc/rfc7946) beschrieben. Es handelt sich um einen linearen Ring d.h. eine Aufzählung der Polygon-Eckpunkte (longitude, latitude WGS 84 ) im Gegenuhrzeigersinn. Der letzte Punkt ist mit dem Ersten deckungsgleich, womit das Polygon vollständig geschlossen ist.

Beispiel:

Masseinheiten

Zur Angabe von Masseinheiten nutzt die API grundsätzlich das internationale Einheitensystem (SI). Weil dies in der Praxis nicht ausreicht, werden zusätzlich auch noch eine Reihe von gebräuchlichen Nicht-SI-Einheiten genutzt. Die Angabe der Masseinheit erfolgt in Form des Einheitenzeichens (Bsp: kg, t, s), inklusive einem allfälligen SI-Präfix (Kilo oder Milli). Zusätzlich sind auch Kombination bzw. Verhältnis-Masseinheiten möglich (Bsp: kg/m³). Für einzelne Ressourcen-Felder ist die Anzahl an zugelassenen Masseinheiten eingeschränkt. Hinweise hierzu gibt die jeweilige Feldbeschreibung.

Dokumente oder Dateien

Dokumente oder Dateien werden in der API in Form von Links bzw. URL's weitergegeben. Konsumenten können den Link nutzen, um die Dateien bei Bedarf herunterzuladen.
Die Autorisierung für das Herunterladen der Dateien steht nicht mit der Autorisierung für den Zugriff auf die API in Verbindung. Deshalb lassen sich die Links auch von Drittsystemen nutzen, welche selbst keinen Zugriff auf die API besitzen. Die zurückgegebenen Links sind dazu mit einem integrierten ressourcenbezogenen „Shared Access Key" ausgerüstet. Diese Key erlaubt ausschliesslich einen lesenden Zugriff auf die Datei und ist während maximal 7 Tage gültig.

Beispiel eines Dokumenten-Links
https://asphalttag-documents.q-plant.com/V1/a69d07c6-091a-4d98-b3ea-5226b61c79d6.pdf?sv=2014-02-14&st=2014-12-23T22%3A18%3A26Z&se=2014-12-23T22%3A23%3A26Z&sr=b&sp=rw&sig=Z%2FRHIX5Xcg0Mq2rqI3OlWTjEg2tYkboXr1P9ZUXDtkk%3D

Ist der Key falsch oder die eingeschränkte Zugriffszeit abgelaufen, antwortet der Service mit einem HTTP-Statuscode: 404 „Not Found"

Callback Subscriptions

Definition Callback Subscriptions

REST-Schnittstellen reagieren nach dem Client-Server-Prinzip auf Anfragen. Sie können jedoch nicht proaktiv Informationen liefern, ohne dass ein Client diese zuvor angefordert hätte. Bei der klassischen REST-Schnittstelle muss jegliche Kommunikation von Client initiiert werden.

Dieser Umstand genügt nicht immer den Anforderungen. Treten auf Seiten des Systems, welches die Schnittstelle anbietet, Ereignisse ein, über die der Client in Echtzeit informiert werden will, so ist dies mit einer REST-Schnittstelle allein nicht möglich. Der Client müsste das Ereignis abfragen, hat jedoch von dessen Eintritt keine Kenntnis. Seine einzige Möglichkeit wäre das Polling - ein regelmässig wiederholtes, kontinuierliches Abfragen der Schnittstelle. Dieses Verfahren ist jedoch ineffizient für beide Seiten. Je kürzer das Abfrageintervall, desto grösser die Last für Client und Server. Je länger das Intervall, desto weniger erfolgt die Datenübertragung in Echtzeit.

Anstelle des Pollings bieten die Q Exchange Schnittstellen hierzu abonnierter Callbacks an. Hierbei wechselt der Client die Rolle und stellt selbst eine eigene REST-Schnittstelle zur Verfügung, die Q Exchange aufruft und das Ereignis übermittelt. Dies geschieht nur, wenn das Ereignis auch wirklich eingetreten ist. Welche Ereignisse übermittelt werden sollen, bestimmt der Client durch sein Abonnement, die sogenannte Subscription.

Beispiele

Durch Callback Subscriptions können externe Systeme unter anderem folgende Ereignisse und deren Daten empfangen.

Voraussetzungen

Für eine Callback Subscription muss das externe System folgende Voraussetzungen erfüllen.

• Bereitstellung einer eigenen API, die für fremde Systeme via Internet erreichbar ist.

• Implementierung derjenigen Endpunkte der API, die in den Referenzen zu Q Exchange beschrieben sind. Die Endpunkte müssen Aufrufe mit den beschriebenen HTTP-Methoden verarbeiten und gesendete Datensätze in den beschriebenen Schemata akzeptieren.

• Um die Authentizität der empfangenen Information sicherzustellen, sollten nur autorisierte Aufrufe zugelassen werden. In diesem Fall müssen bei der Subscription gültige Crendentials hinterlegt werden.

• Beantwortung korrekter Aufrufe mit dem Response Code 200 OK bzw. im Fall von HTTP-POST-Aufrufen mit 201 Created. Andere Response Codes werden von Q Exchange als Fehler interpretiert und können evtl. zum Aussetzen des Abonnements führen - siehe Abschnitt: "Fehlerbehandlung und Status".

Subscriptions anlegen oder verwalten

Q Exchange Endpunkte und Methoden zum anlegen, abfragen, löschen oder (nach einem Fehler) reaktivieren von Subscriptions sind auf der /wiki/spaces/~829548211/pages/206602255 detailliert beschrieben.

Fehlerbehandlung und Status

Jede Subscription besitzt einen Status mit einem der folgenden Werte.

Neu angelegte Subscriptions sind stets active und bleiben dies mindestens so lange, bis bei der Übermittlung ihres Events ein Fehler auftritt. Dies ist immer dann der Fall, wenn der Aufruf an die Susbsciber-Schnittstelle mit einem anderen Response Code als 200 OK bzw. 201 Created beantwortet wird.

Q Exchange unterscheidet zwischen folgenden drei Fehlerarten. 

Semantic Fault (inhaltlicher Fehler)

Empfängt Q Exchange nach einer Event-Übermittlung den Response Code 400 Bad Request, dann wird von einem semantischen, d.h. inhaltlichem Fehler ausgegangen. Die Transaktion selbst war erfolgreich, doch die übermittelten Daten entsprechen in Form, Schema oder Inhalt nicht dem, was der Empfänger erwartet. Q Exchange reagiert darauf mit folgenden Aktionen.

• Die Subscription verbleibt im Status active und sendet weiter Nachrichten.

• Die Transaktion, die mit 400 Bad Request beantwortet wurde, wird nicht wiederholt.

• Die evtl. fehlerhaft übertragene Ressource wird auf Senderseite mit einem Fehler gekennzeichnet, die dem dortigen Anwender über das Problem informiert.

Transient Fault (vorübergehender Übermittlungsfehler)

Empfängt Q Exchange nach einer Event-Übermittlung einen der oben gelisteten Response Codes, dann wird von einem vorübergehenden Problem bei der Datenübermittlung ausgegangen. Q Exchange reagiert darauf wie folgt.

• Der Status der Subscription wird auf failed gesetzt.

• Die gescheiterte Transaktion wird erneut versucht: 15 Minuten lang alle 10 Sekunden, später alle 60 Sekunden.

• Gelingt die Transaktion bei einem der Folgeversuche, dann wechselt der Status der Subscription zurück auf active.

• Ist die Transaktion nach 12 Stunden noch immer nicht gelungen, dann werden die Versuche eingestellt. Es wird dann von einem dauerhaften Übermittlungsfehler ausgegangen. Dies hat neben den unten gelisteten Konsequenzen auch zur Folge, dass der Status der Subscription auf aborted wechselt.

• Events werden auch im Fehlerfall nur in der Reihenfolge übermittelt, in der sie auftreten. Solange ein einzelnes Event nicht erfolgreich übermittelt wurde, wird die Übermittlung nachfolgender Events zurückgestellt.

Continuing Fault (dauerhafter Übermittlungsfehler)

Empfängt Q Exchange nach einer Event-Übermittlung einen anderen Response Code, der nicht zu den oben genannten gehört, so wird dies als dauerhaften Fehler in der Datenübermittlung interpretiert. Q Exchange reagiert darauf wie folgt.

• Der Status der Subscription wird auf aborted gesetzt.

• Dieses und alle nachfolgenden Nachrichten werden auf Senderseite zwischengespeichert. Solange das Problem jedoch nicht behoben und der Subscription-Status weiterhin aborted ist, wird kein weiterer Übertragungsversuch unternommen.

• Der Zeitpunkt wird in der Subscription im Feld "AbortedDto" dokumentiert. Die Ursache wird im Feld "FailureCause" vermerkt. Beide Felder können per GET-Abfrage abgerufen werden.

Die Ursache eines Continuing Fault müssen in der Regel manuell behoben werden. Anschliessend kann der Subsciption-Status durch einen entsprechenden Aufruf an Q Exchange wieder zurück auf active gesetzt werden. Ist dies geschehen, dann werden nachträglich alle ausstehenden Nachrichten übertragen, die in der Zwischenzeit auf Senderseite aufgetreten sind und dort zwischengespeichert wurden. Anschliessend läuft die Subscription weiter wie vor dem Fehler.