Webservice Dokumentation

Vorbereitung

Damit Sie den Webservice nutzen können muss zunächst ein Suchprofil eingerichtet werden. Beim Speichern des Suchprofils muss darauf geachtet werden, dass dieses mit der Option "Cloud Connect" angelegt wird:

Falls Sie diese Option beim Speichern Ihres Suchprofils nicht sehen, ist der Webservice für Ihren Account noch nicht freigeschaltet worden. Nehmen Sie in diesem Fall bitte Kontakt mit unserem Kundenservice (kundenservice@ibau.de) auf.

Die ID des Suchprofils kann seiner URL entnommen werden, z.B

https://login.ibau.de/projects/21425/0

• Nach der Einrichtung des Suchprofils kann dieses per Webservice erst ab dem nächsten Tag abgerufen werden!
• Neue Ergebnisse können nur an den beim Speichern des Suchprofils aktivierten Tagen abgerufen werden!
• Bei dem Anlegen des Suchprofils können Sie festlegen, an welchen Tagen automatisch neue Treffer in den Webservice gepusht werden sollen. Ob ein Suchprofil in den Webservice pusht, erkennen Sie am grünen Wolkensymbol neben dem Suchprofilnamen.

• Standardmäßig werden alle neuen Suchprofiltreffer und alle Updates zu diesen Treffern an den von Ihnen definierten Tagen in den Webservice gepusht. Wenn Sie die Treffer nur einmalig, also ohne Updates, haben wollen, können Sie unten statt "Alle Updates" die Option "Einmalbelieferung" auswählen. Sie erhalten den Treffer dann nur einmal per Schnittstelle und zwar dann, wenn der Treffer zum ersten Mal zu Ihrem Suchprofil passt am nächstmöglichen Tag, den Sie für die Übertragung ausgewählt haben.
• Das automatische Pushen der Treffer in den Webservice erfolgt bis zu einmal täglich.
• Neben dem automatischen Pushen der Treffer können auch manuell Projekte oder Bekanntmachungen in die Schnittstelle gepusht werden. Dies ist im nächsten Abschnitt erklärt. Damit können Sie interessante Projekte oder Bekanntmachungen sofort per Schnittstelle verfügbar machen.

Wenn Sie ein Projekt oder eine Bekanntmachung direkt in der Schnittstelle verfügbar haben wollen, können Sie folgendermaßen vorgehen:

• Gehen Sie in eins Ihrer Suchprofile mit grüner Wolke.
• Wählen Sie dort die Checkbox neben dem Projekt oder der Bekanntmachung aus, die Sie direkt in der Schnittstelle verfügbar haben wollen.
• In der Funktionsleiste über der Trefferliste erscheint ein Wolkensymbol (Cloud Connect). Klicken Sie auf dieses Symbol:

• Oben rechts erscheint kurz in Grün die Bestätigung, dass die Entitäten erfolgreich nach Cloud Connect übertragen wurden.
• Die gerade ausgewählten Projekte oder Bekanntmachungen sind nun direkt unter dem zuvor ausgewählten Suchprofil im Webservice verfügbar.

Umgebungen

Je nachdem, ob Sie bei Infobau oder bei Ibau Kunde sind, müssen Sie eine andere URL für den Webservice nutzen:

Produkt	Webservice-URL
Ibau Xplorer	https://api.login.ibau.de/
Infobau Xplorer	https://api.login.infobau-muenster.de
Greenprofi Xplorer	https://api.login.greenprofi.de

Login

Um sich mit dem Web-Service zu verbinden, muss zunächst ein Login erfolgen. Dieser kann unter dem Endpunkt POST /login_check erreicht werden. Hier wird eine Anfrage mithilfe des Benutzernamens und Passwortes des zur Verfügung gestellten Benutzers gestellt.

Ein erfolgreicher Login liefert einen JWT-Token und einen entsprechenden Refresh-Token. Ersteres wird für jeden weiteren Kontakt mit der Schnittstelle benötigt. Letzteres wird benötigt, um sich nach Ablauf des Tokens einen neuen Token ausstellen zu lassen.

Wenn Sie einen normalen Benutzer haben, welcher sich nicht mehrfach gleichzeitig einloggen kann, bekommen Sie auch einen Security-Cookie. Diesen müssen Sie ebenfalls bei jedem Aufruf mit sich führen.

Hinweis zur Session-Verwaltung: Beim Testen der Schnittstelle ist zu beachten, dass pro Benutzerkonto nur eine aktive Session erlaubt ist. Wenn Sie sich über die Schnittstelle mit Benutzername und Passwort einloggen, wird eine bestehende Browser-Session automatisch beendet. Das gleiche gilt umgekehrt: Sobald Sie sich erneut im Browser anmelden, wird die bestehende API-Session beendet. Dies sollte insbesondere bei Entwicklungs- und Testarbeiten berücksichtigt werden.

Der JWT ist standardmäßig eine Stunde lang gültig. Benötigt man eine längere Session, kann man den Token mithilfe des Refresh-Tokens unter POST /token/refresh wie folgt erneuern:

Das Ergebnis dieser Abfrage ist identisch mit der Login-Abfrage. Der Refresh-Token ist 8 Stunden lang gültig und wird ebenfalls erneuert bei jedem Aufruf.

Abholen der Daten

Es gibt drei mögliche Endpunkte entsprechend der im Xplorer verfügbaren Produkte.

SearchProfile-IDs sind strikt an den jeweiligen Endpunkt (Objekttyp) gebunden und können nicht zwischen verschiedenen Endpunkten wiederverwendet werden. Wird ein SearchProfile mit einem nicht passenden Endpunkt verwendet, führt dies zu einem „SearchProfile with given id not found"-Fehler, auch wenn die ID grundsätzlich existiert.

Hinweis: Welche Objekte bei Ihnen verfügbar sind, hängt von Ihrem Ibau- bzw. Infobau- Rahmenvertrag ab.

Das Abholen der Daten findet über einen der o.g. Endpunkte per GET statt, z.B. /web_service/all_pn_headers/. Hierzu wird der bereits erhaltene JWT-Token und die ID von dem zuvor angelegten Suchprofil benötigt. Der Token wird mittels Authorization-Header mitgegeben. Die Suchprofil-ID mithilfe eines GET-Parameters wie folgt:

Diese Abfrage liefert nun, sofern vorhanden, die neuen Daten Ihres Suchprofils. Das Format der Daten kann mittels des Accept-Headers entschieden werden. Die folgenden Optionen stehen standardmässig zur Verfügung:

• Accept: application/xml
• Accept: application/json
• Accept: application/ld+json

Für neue Integrationen empfehlen wir die Nutzung des Formats application/json, da dieses Format in den meisten Programmiersprachen und Integrationsplattformen standardmäßig unterstützt wird.

Projektbilder können über das Feld projectFiles innerhalb eines Projektdatensatzes abgerufen werden.

Die Bild-URL wird nicht direkt als vollständiger öffentlicher Link ausgeliefert, sondern als relativer Pfad innerhalb der API-Struktur. Der Abruf funktioniert nur mit einer gültigen authentifizierten API-Session.

Das jeweilige Projekt muss im Feld: /root/hydra_member/projectFiles einen Eintrag mit folgendem Dateityp enthalten: /root/hydra_member/projectFiles/file/fileType/code = PROJECT_IMAGE. Nur in diesem Fall existiert ein Projektbild.

Der eigentliche Download-Pfad befindet sich unter: /root/hydra_member/projectFiles/file/url. Dieser relative Pfad muss mit der API-Basis-URL kombiniert werden.

Wird diese URL innerhalb einer gültigen API-Session aufgerufen, liefert die Schnittstelle direkt das Bild als Response zurück.

Hinweis: Die Bildinformationen sollten direkt beim Abruf eines Projekts verarbeitet werden. Es empfiehlt sich zu prüfen, ob projectFiles gefüllt ist und ein Eintrag vom Typ PROJECT_IMAGE vorhanden ist.

Datensätze stehen für insgesamt 35 Tage in der Schnittstelle zur Verfügung, nachdem sie durch ein Suchprofil in den Webservice übertragen wurden. Nach Ablauf dieses Zeitraums werden die Daten automatisch aus der Schnittstelle entfernt. Falls die Daten weiterhin benötigt werden, müssen sie erneut durch ein entsprechendes Suchprofil in die Schnittstelle gepusht werden.

Eine Beschreibung der Datenfelder für die verschiedenen Objekttypen sowie Beispiele im JSON-Format finden Sie weiter unten in dieser Dokumentation.

Falls Sie keine korrekte Suchprofil-ID mitgeben, erhalten Sie eine Fehlermeldung inklusive der für diesen Objekttypen verfügbaren Suchprofil-IDs:

Für alle Datensätze können direkte Backlinks in den Xplorer erzeugt werden. Der Link wird anhand der jeweiligen ID des Datensatzes aufgebaut. Wichtig ist, dass die korrekte Basis-URL und der passende Endpunkt zur jeweiligen Datenstruktur verwendet werden.

Die jeweilige ID stammt immer aus dem entsprechenden API-Endpunkt der jeweiligen Datenstruktur.

Bestätigung der Abholung

Der Web-Service liefert Ihnen die Daten Ihres Suchprofils und merkt sich dabei, was Sie bereits abgeholt haben. Standardmäßig bekommen Sie 10 bzw. 20 Datensätze (Projekte bzw. Bekanntmachungen) pro Aufruf der oben genannten Endpunkte. Damit eventuelle Fehler behandelt werden können, müssen Sie das Abholen jedoch bestätigen um an die nächsten 10 bzw. 20 Datensätze zu kommen. Hierzu bieten wir Ihnen zwei Wege:

Der sicherste Weg keine Daten zu verlieren ist es, uns nach dem Abholen separat mitzuteilen, dass Sie die Daten sauber bekommen haben. Dies geschieht mithilfe des Endpunktes POST /web_service/acknowledge/. Hierzu wird ein JSON-Objekt erwartet, welches sowohl die Suchprofil-ID von Ihnen enthält als auch die IDs der Datensätze, welche Sie uns Bestätigen wollen. Hierzu ein Beispiel: