Allgemein
Im Folgenden werden verschiedene Schnittstellen vorgestellt, über welche es möglich ist Points of Interest (POIs) und Veranstaltungen zu beziehen.
Authentifizierung
Die Abfrage erfolgt über eine Endpoint URL und die Authentifizierung mit einem Nutzernamen und dem entsprechenden API Key. Diese können der Abfrage über Custom Header mitgegeben werden. POIs und Veranstaltungen sind Tourismusorganisationen, in der API als "organisation_no" bezeichnet, zugeordnet. Beim Anlegen Ihres API Zuganges können der jeweiligen API diese Organisationen zugeordnet werden, wodurch Sie Zugang auf die dazugehörigen POIs und Veranstaltungen erhalten. Neben den einzelnen Organisationen gibt es auch eine Möglichkeit der Gruppierung ("group_no"), welche aus mehreren Organisationen besteht.
Die Custom Header welche Sie zur Authentifizierung nutzen können
Custom Header | Typ | Erklärung |
---|---|---|
AuthorizationUsername | string | Der Ihnen zugewiesene Nutzername für den API Zugang |
AuthorizationKey | string | Ihr API Key |
Requests
Allgemein sollte bei Requests beachtet werden diese aus Sicherheitsgründen immer über HTTPS zu stellen. Außerdem sollte zur Reduzierung des Traffics bei der Implementierung der Schnittstellen darauf geachtet werden, nicht bei jedem neuen Seitenaufruf eine neue Anfrage an die API zu senden, sondern die erhaltenen Daten zwischen zu speichern. Beispiele für verschiedene Requests sowie die Response finden Sie unter der jeweiligen API
Requests mit Filtern
Es ist möglich einer Request über die entsprechende URL verschiedene vorgegebene Filter mit zu geben. Die Standardfilter beider APIs sind "organisation_no" und "group_no". Über "organisation_no" lassen sich die POI-Daten einer einzelnen Organisation über deren Id abfragen. Eine "group_no" ermöglicht eine gleichzeitige Abfrage der POI-Daten mehrerer Organisationen. Diese Gruppierungen können durch einen Supportmitarbeiter beim Einrichten des API-Zugangs angelegt werden. Weitere Filter finden Sie unter der jeweiligen API.
Allgemeine Requests
Werden der Anfrage keine Filter übergeben, so werden alle für Ihren API Zugang freigegebenen POIs bzw. Veranstaltungen ausgegeben.
Response
Die Response der APIs sind im JSON-Format und enthalten immer einen Status und einen HTTP Status Code. War die Anfrage erfolgreich, so wird neben diesen auch der angefragt Datensatz zurückgeliefert.
Wichtig ist, dass eine Antwort nicht immer alle Daten enthalten muss. Heißt, dass falls beispielsweise bei einem POI kein Bild oder Logo angegeben wurde, dieses Feld in der Antwort als leer gekennzeichnet ist und nicht alle möglichen Knoten der Baumstruktur dargestellt werden.
Error Handling
Sollte ein Fehler aufgetreten sein, so wird außerdem ein Custom Error Code samt Fehlermeldung ausgegeben, welche diesen genauer beschreibt.
HTTP Status Code | Custom Error Code | Message |
---|---|---|
400 | 1 | Invalid username or password |
400 | 6 | Invalid allocation format. Has to be a valid organisation_no or group_no |
400 | 10 | Invalid allocation. Has to be organisation_no or group_no |
400 | 14 | The given date is invalid. |
403 | 2 | No access to the entered API |
403 | 5 | No access to the entered organisation_no or group_no |
401 | 7 | No username set in header |
401 | 8 | No API key set in header |
401 | 11 | Username or password not correct |
404 | 3 | The given allocation doesn't exist |
400 | 4 | The request contains invalid parameters |
404 | 13 | The given version number doesn't exist |
429 | 9 | Too many request in the last 10 seconds |
500 | 12 | Procedural error |
Beispiel für eine fehlerhafte Request
Hier sehen Sie eine beispielhafte Rückmeldung auf eine fehlerhafte Anfrage.
{
"api_type": "POI",
"api_version": "1.0",
"status": "fail",
"http_status_code": 403,
"message": "No access to the entered organisation_no or group_no",
"custom_error_code": 5
}
Versionierung
Die Schnittstellen sind versioniert und bestimmte Versionen können über den GET-Parameter "v={versionsNummer}" in der URL gesetzt werden. Wird keine Version angegeben, so wird die neuste Version für die Request genutzt.
Die für die Request verwendete Version der Schnittstelle ist außerdem am Anfang jeder Response zu sehen.
Push Benachrichtigungen
Damit Sie automatisch über neue, geänderte oder entfernte POIs oder Veranstaltungen benachrichtigt werden, können Sie beim Anlegen Ihres Zuganges eine Push URL hinterlegen lassen. An diese werden dann Details der Änderung gesendet. Dazu gehören der Name der API, die Id des POIs oder der Veranstaltung, die Art der Änderung und eine URL über welche die aktuellen Details der POI oder der Veranstaltung abgerufen werden können. Im Falle einer Löschung wird entsprechend kein Link ausgegeben.
Beispiel für eine Push Benachrichtigung
Anhand eines Beispieles sehen Sie nachfolgend das Schema einer Push Benachrichtigung
{
"api_type": "poi",
"id": 1234,
"action": "UPDATE",
"feedURL": "https://www.optimale-praesentation.de/comm/universal/poi/1234"
}
Mögliche Werte der Attribute der Benachrichtigung und deren Bedeutung.
Attribut | Typ | Werte | Erklärung |
---|---|---|---|
api_type | string | poi, event | Der Typ der API, gibt an ob ein POI oder eine Veranstaltung geändert wurde. |
id | int | Die Id des erstellten, gelöschten oder geänderten POIs oder Veranstaltung. | |
action | string | INSERT, UPDATE, DELETE | Gibt an, ob ein POI oder eine Veranstaltung erstellt, geändert oder gelöscht wurde. |
feedURL | string | Die URL über welche die aktuellen Details abgerufen werden können. |
Request Limitierung
Zur Reduzierung der Auslastung der Schnittstellen, wurde ein Limit an Anfragen pro Nutzer pro Intervall festgelegt. Sollte dieses Limit erreicht werden so antwortet die Schnittstelle mit dem entsprechenden HTTP Status Code.
Zugang erhalten
Um einen Zugang zu erhalten wenden Sie sich bitte an support@secra.de.