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.

results matching ""

    No results matching ""