API-Dokumentation

mein.toubiz ist eine webbasierte touristische Datenbanklösung zur Verwaltung von strukturierten Daten wie POIs (Point of interest), Gastronomie, Veranstaltungen, Touren, Unterkünfte etc.

mein.toubiz ist Mandantenfähig und verfügt über eine leistungsfähige API zum Abruf oder Manipulation von Daten.

Datenmodell

Datentypen

mein.toubiz arbeitet mit vier verschiedenen Datentypen: Punkt-Daten, Linien-Daten, Veranstaltungs-Daten und Medien. Bei Punkt- und Linien-Daten wird im System allgemein von Artikeln gesprochen. Unter allen Daten kann es Verknüpfungen geben; so werden Punkt-Daten beispielsweise als Veranstaltungsort oder Veranstalter verwendet.

 

D.h. ein als POI erfasstes Restaurant kann bei entsprechender Kategorisierung auch als Veranstaltungsort verwendet werden und muss nicht separat erstellt werden.

  • Unter Punkt-Daten werden Daten verstanden welche sich geografisch mit einem Geo- Punkt abbilden lassen. Z.B. POIs, Gastronomie, Unterkünfte.

  • Unter Linien-Daten werden Daten verstanden welche sich geografisch mit einer Linie abbilden lassen. Z.B. Wanderung, Spaziergänge etc.

  • Hierunter werden zeitbezogene Daten verstanden. Dies können klassische Veranstaltungen aber auch buchbare Bausteine zu einem bestimmten Datum sein.

  • Unter Medien werden Medieninhalte wie Bilder, Dokumente etc. verstanden. Medien können in allen Daten referenziert werden.

  • Für die verschiedenen Datentypen sind unterschiedliche Kategorien-Bäume vorgesehen. Jede Kategorie kann kategoriespezifische Felder mitbringen, welche spezifische Eigenschaften für die Kategorie zur Verfügung stellt. Beispiel: „Küchenstil“ in der Kategorie „Essen & Trinken“. In der API-Dokumentation wird hierbei von dynamischen Feldern gesprochen.

  • Inhalte in mein.toubiz können mehrsprachig vorliegen. Die Standardsprache ist deutsch und wird angewendet, wenn keine explizite Sprache übergeben wird.

  • Artikeln und Medien können CC-Lizenzen zugeordnet werden. Auf diese Lizenzinformationen muss bei der Weiterverarbeitung von Daten zwingend Rücksicht genommen werden.

API

Allgemein

mein.toubiz stellt eine REST-Schnittstelle mit unterschiedlichen Endpunkten zur Verfügung. Die Aufgabenbereiche der Endpunkte sind durch die Bezeichnung klar erkennbar.

 

Antworten werden nach dem Minimalprinzip geliefert, werden zusätzliche Informationen benötigt müssen diese explizit angefragt werden.

 

In jeder Antwort werden, neben den eigentlichen Daten, Hinweise und weitere Informationen für Entwickler geliefert, um die Integration der Schnittstelle zu erleichtern.

 

Mehrere Versionen der API werden über mehrere URLs zur Verfügung gestellt; somit besteht Kompatibilität bei Änderungen. Das _warning property wird für Hinweise zu Änderungen verwendet.

  • JSON ist die Standardserialisierung für alle Parameter. Dies beinhaltet sowohl die Rückgabewerte der API als auch die POST und PATCH Body's.
    Außnahmen (z.b. für Dateiuploads) werden explizit dokumentiert.

    Alle Daten (in Rückgabewerten und Anfragen) sind nach ISO8601 formatiert. 

    • Beispiel für Datum: 2017-01-12
    • Beispiel für Datum mit Uhrzeit: 2017-01-12T14:32
  • Die Authentifizierung erfolgt über einen hinterlegten API Key. Dieser Key kann auf mehrere Weisen übergeben werden:

    • Via Authorization: Bearer abc123 Header (empfohlen)
    • Via ?api_key=abc123 URL Parameter (nicht empfohlen, jedoch für die einfachere API Discovery unterstützt)
  • Es wird stets ein für die Anfrage relevanter Statuscode zurückgegeben. Beispiele für relevante Statuscodes:

    • 200: OK Die Anfrage war erfolgreich.
    • 400: Bad Request Die Anfrage des Entwicklers war invalide.
    • 403: Forbidden Die Anfrage ist dem aktuellen Nutzer nicht erlaubt.
    • 404: Not Found Die Angefragte Resource existiert nicht.
    • 429: Too Many Requests Der Nutzer hat zuviele Anfragen in zu kurzer Zeit gesendet. 
    • 500: Internal Server Error Ein unbestimmter Fehler auf dem Server ist aufgetreten.
  • Für Veranstaltungen muss zwingend ein Veranstaltungsort übergeben werden (location). Ein Veranstaltungsort kann ein beliebiger Punkt-Datensatz sein, z.B. ein POI.

     

    Die zur Verfügung stehenden Punkt-Daten müssen zunächst abgerufen und mit dem Dritt- System gemappt werden.

Noch keinen API-Zugang?

Dann erfahre mehr dazu und beantrage deinen Zugang!