Schnittstellen des Suchdienstes
Um den vielfältigen Anforderungen gerecht zu werden, ist der Suchdienst mit zahlreichen Schnittstellen ausgestattet. Über die internen Schnittstellen ist der Dienst an weitere Komponenten des Portalverbund Onlinegateways (PVOG) angeschlossen, insbesondere den Sammlerdienst, der die Nutzdaten im aufbereiteten XZuFi-Format anliefert. Weiterhin ist der Suchdienst per interner Schnittstelle an Elasticsearch angebunden. Die auf diese Weise bereitgestellte verteilte Such- und Analysefunktionalität ist ein wesentlicher Faktor, um Suchanfragen schnell und mit einer hohen Treffergenauigkeit zu beantworten. Elasticsearch bietet eine Schnittstelle auf Basis von REST und JSON für Suchanfragen an, welche durch den Suchdienst mit einer REST-Fassade nach außen gekapselt wird.
Die Beschreibung der verschiedenen Endpunkte mit den Abfragedetails befinden sich unter Suchdienst Schnittstellen.
Diese eingehenden Suchanfragen umfassen Verwaltungsleistungen, Organisationseinheiten sowie Ortsangaben und werden über die externen Schnittstellen beanwortet. Es handelt sich um REST-Schnittstellen, die je nach Konsumentenanforderung die gewünschten Daten in unterschiedlichem Format liefern. Aktuell können alle Daten als JZuFi (XZuFi als JSON) oder in einer reduzierten, dafür aber schlanken und auf die Bedürfnisse von mobilen Endgeräten zugeschnittenen Form als JSON bezogen werden. Bei allen Anfragen kommt dabei das HTTPS-Protokoll zum Einsatz, um den zahlreichen Sicherheitsanforderungen zu genügen. Der Bürger kann auf einem angeschlossenen Verwaltungsportal nach einer beliebigen Verwaltungsleistung suchen und erhält als Ergebnis eine Trefferliste mit Ergebnissen aus dem gesamten Verbund.
Die externen Schnittstellen sind ohne Authentifizierung öffentlich aus dem Internet erreichbar.
Externe Schnittstellen
Externe Schnittstellen erlauben es, öffentlich verfügbare Daten abzurufen und beispielsweise in einem Verwaltungsportal zu nutzen. Diverse Webseiten wie das OZG-Dashboard des Bundesministerium des Inneren und auch die PVOG-eigene Servicesuche Bund beziehen Daten direkt über die externen Schnittstellen. Aber auch interessierte Bürgerinnen und Bürger können dort nach Onlinediensten, Organisationseinheiten oder Verwaltungsleistungsdaten suchen. Dafür sind Technikkenntnisse nötig.
Versionierung der Schnittstelle
Um bestmögliche Kompatibilität zu gewährleisten, ist im Suchdienst eine Schnittstellenversionierung umgesetzt, sodass externe Konsumenten in einem selbstbestimmten Tempo auf die neuen Schnittstellenversionen migrieren können. Hierfür wird die Versionsnummer des Pfades inkrementell erhöht, die vorherige Schnittstelle als deprecated deklariert und die Dokumentation der Schnittstelle entsprechend angepasst. Die Versionierung erfolgt über eine Versions-Komponente (z.B. v1, v2, …) des Pfads einer jeden externen Schnittstelle.
Neue Schnittstellenversionen können jederzeit mit einem PVOG-Release veröffentlicht werden. Die alten, als deprecated markierten Schnittstellen bleiben für die Übergangszeit bestehen, während parallel die neuen Schnittstellen in allen Umgebungen bereitstehen, um die Anpassung der Anbindung auf Konsumentenseite nach deren Tempo zu ermöglichen. Die Schnittstellen, die als deprecated markiert sind, werden nach einer Übergangszeit von min. drei Monaten entweder zum 01.02., 01.05., 01.08. oder 01.11. dauerhaft deaktiviert und sind somit nicht mehr nutzbar.
Weitere Informationen zu DeprecationsLinkgenerator
Um die Nutzenden direkt zu den relevanten Inhalten zu führen, können Verantwortliche für Redaktionssysteme bzw. Portale mit dem Linkgenerator sogenannte Deeplinks erzeugen.
Es können zwei Arten dieser Links erzeugt werden:
- Links mit einem ARS (amtlicher Regionallschlüssel) führen Nutzende direkt zur Auswahlseite für die Anliegen am jeweiligen Ort.
- Links mit einem Anliegen oder einem Leistungsschlüssel führen die Nutzenden auf eine spezielle Suchseite. Dort müssen sie nur noch den jeweiligen Ort oder eine PLZ eingeben. Anschließend erfolgt die direkte Weiterleitung zu den oder der entsprechenden Verwaltungsleistung(en). Dies vereinfacht das Auffinden der richtigen Leistung deutlich.
Um einen Deeplink zu erzeugen, geben sie entweder eine PLZ / Ort oder ein Anliegen / einen Leistungsschlüssel in das entsprechende Feld im Linkgenerator ein. Klicken sie danach auf "Deeplink generieren". Der Generator erzeugt den Link im darunter liegenden Feld "Deeplink". Von dort können sie den Link kopieren und in ihrem Redaktionssystem weiter verwenden.