Überblick über das Developer Studio

Mit dem Developer Studio wollen wir Ihnen einen Überblick über unsere aktuell verfügbaren APIs ermöglichen und Ihnen Hilfestellungen bei der Integration geben. Sie finden alle derzeit über dieses Studio veröffentlichten APIs im Menüpunkt APIs. Hier können Sie die einzelnen APIs selektieren und sich die implementierten Endpunkte und deren technischen Spezifikationen ansehen. Sie finden für jede API und jeden Endpunkt eine kurze Beschreibung und eine Angabe zum möglichen Anwendungsfall, für den diese API gedacht ist, sowie gegebenenfalls Einschränkungen oder weitere Hinweise. Zusätzlich zur Beschreibung können Sie sich auch eine YAML- oder JSON-Datei für die jeweilige Version des Endpunkts herunterladen.

Voraussetzungen für die Integration unserer APIs

Geschäftsverhältnis zur Prohyp Für die Nutzung der meisten APIs benötigen Sie einen Vermittler-Account in ehyp – unserer Baufinanzierungsplattform. Dieser beinhaltet neben Ihren Kontaktdaten auch diverse individuelle Einstellungen, auf die sich unsere APIs beziehen. Die Erstellung eines Accounts ist ganz einfach. Bitte nutzen Sie auf unserer Website www.prohyp.de die Funktion „Jetzt Partner werden“. Nach Eingabe Ihrer Kontaktdaten werden wir Ihren Account anlegen und Ihnen den Kooperationsvertrag zukommen lassen. Unsere Nutzungsbedingungen Für die Nutzung unserer APIs gelten bestimmte Voraussetzungen, deren aktuellste Version Sie in der Rubrik Nutzungsbedingungen finden. Bitte lesen Sie diese aufmerksam durch. Sollten Sie mit den Bedingungen nicht einverstanden sein, ist die Integration und Nutzung unserer APIs leider nicht möglich. Vor Freischaltung der APIs werden Ihnen die Nutzungsbedingungen nochmals zur Verfügung gestellt - mit der Bitte diese zu bestätigen. Bei Fragen wenden Sie sich gerne an am@prohyp.de.

Authentifizierung über Token

Die Authentifizierung für unsere APIs erfolgt mittels Token. Diesen Token können Sie über die Authorization API abrufen. Die für den Aufruf dieser API relevanten Daten erhalten Sie nach Anlage Ihres Accounts. Wir wollen Ihnen den Zugang zu unseren APIs möglichst einfach und einheitlich ermöglichen. Dennoch gibt es einige APIs, die aufgrund ihres Alters eine andere Methode der Authentifizierung benötigen. Die Information finden Sie in der jeweiligen API-Dokumentation.

Authentifizierung über API Keys

Für die Benutzung unserer APIs ist eine Authentifizierung aller Aufrufe mittels API Key notwendig. Daher muss Ihr individueller API Key als Header in jedem Aufruf an unsere APIs mit übertragen werden. Für die unterschiedlichen Systemlandschaften erhalten Sie jeweils einen gesonderten API Key. Ihre individuellen API Keys können Sie beim Ausstellen Ihrer Anmeldedaten für die Authorization API erfragen.

Grundsätzliches

Verfügbarkeit von veralteten APIs Manchmal sind neue Features oder Technologien so andersartig, dass Sie nicht in eine bestehende API integriert werden können. In diesem Fall werden wir eine neue Version der API bereitstellen. Um die neuen Features zu nutzen, müssen Sie auf die neue Version der API wechseln. Wir werden die alte Version für einen gewissen Zeitraum weiter betreiben, um Ihnen die Möglichkeit zur Planung des technischen Umbaus zu geben. APIs, die veraltet sind, werden in der API-Dokumentation als DEPRECATED markiert und zu einem bestimmten Zeitpunkt deaktiviert. Wir empfehlen diese APIs nicht mehr neu zu implementieren, sondern die aktuelle Version zu nutzen.

Pagination Unsere APIs verwenden cursor basierte Pagination, um Performance und geringen Netzwerkverkehr sicherzustellen. Sie ist für alle Endpunkte verpflichtend, die potenziell große Datenmengen zurückliefern. Ergebnisse werden zusammen mit Paging Metadaten zurückgegeben. Cursor Ein Cursor ist eine zufällig generierte Zeichenkette, die auf ein Element der Ergebnisliste verweist. Wird dieses Element gelöscht, verliert der Cursor seine Gültigkeit. Hinweis Cursor dürfen clientseitig nicht gespeichert oder als dauerhaft gültig betrachtet werden. Unterstütze Parameter

• before / after – markieren Beginn bzw. Ende der aktuellen Seite
• limit – maximale Anzahl der Ergebnisse (kann durch Filterung geringer ausfallen)
• previous – Link zur vorherigen Seite (fehlt = erste Seite)
• next – Link zur nächsten Seite (fehlt = letzte Seite)

Extensible Enums & Tolerant-Reader-Pattern Unsere APIs verwenden erweiterbare Enums.

• Mit x-extensible-enum gekennzeichnete Felder listen die aktuell unterstützten Werte.
• Diese Liste kann sich im Zeitverlauf ändern.

• Unbekannte Enum-Werte dürfen nicht zu Fehlern führen.
• Nicht unterstützte, gesendete Werte werden vom Server ignoriert und als null interpretiert.

Nutzung von Postman Collections und Environments Zur Unterstützung bei der ersten Anbindung unserer APIs stellen wir für ausgewählte APIs Postman Collections zur Verfügung. Diese dienen als optionales Hilfsmittel, um API Endpunkte kennenzulernen, Requests zu testen und Beispielanfragen nachzuvollziehen. Sofern verfügbar, stehen die Postman Collections in der jeweiligen API Beschreibung zum Download bereit. Zusätzlich bieten wir im Dashboard Postman Environments an. Diese ermöglichen es, API Tests einfach an unterschiedliche Umgebungen anzupassen, indem umgebungs-spezifische Variablen wie Base URLs oder Authentifizierungsparameter zentral gepflegt werden.

Bei Fragen

Wenn im Zuge der Integration oder des Betriebs unserer APIs Fragen auftreten, die sich durch die API-Dokumentation und die bereitgestellten Beispieldateien, (z.B. Postman-Collections für beispielhafte API-Calls) nicht beantworten lassen, können Sie sich gerne an am@prohyp.de wenden.