BayernPortal (REST API Dokumentation) - Version 3

Diese Dokumentation über das REST API und die Ressourcen richtet sich in erster Linie an IT-Dienstleister und Entwickler, die Daten aus dem BayernPortal in kommunale oder staatliche Webauftritte integrieren wollen.

Wir haben uns dafür entschieden, die Versionsnummer des REST API an die Versionsnummer der funktionell identischen SOAP-Schnittstelle anzugleichen. Daher gibt es bereits jetzt eine Version 3 des REST API, obwohl es keine Version 1 und 2 gibt.

Da das REST API auf offenen Standards basiert, kann es mit fast jeder Programmiersprache genutzt werden.

Struktur der REST URIs

Das REST APIs stellt einen Zugriff auf Ressourcen über URI-Pfade bereit. Ihre Applikation benutzt das REST API, indem sie einen HTTP-Request sendet und den Response analysiert bzw. verarbeitet (z.B. als HTML-Seite aufbereitet). Das REST API bietet wahlweise XML und JSON als Datenaustauschformat. Bisher gibt es nur Anwendungsfälle für die Standard-HTTP-Methode GET.

URIs einer REST API Ressource haben die folgende Struktur:

https://host:port/context/rest/api-name/api-version/resource-name

Derzeit sind unter dem API-Namen allgemein die folgenden Ressourcen in den angegebenen API-Versionen verfügbar:

Verfügbare Repräsentationen

Die gewünschte Repräsentation wird über den HTTP-Header Accept angegeben. Mögliche Werte sind:

Warndreieck Bitte beachten Sie, die bisherige Angabe der gewünschten Repräsentation als URL-Suffix (.xml oder .json) ist nicht mehr zulässig!

Authentifizierung

Für die Benutzung des REST API müssen Sie sich per HTTP Basic (über SSL) authentifizieren. Eine Benutzerkennung erhalten Sie von der zentralen Redaktion beim Bayerischen Staatsministerium für Digitales .

Index

Hier folgt die genauere Beschreibung aller Schnittstellen des REST API, die vom BayernPortal angeboten werden.

Ressources

Ressources

/rest/allgemein/v3/dienststellen

Methode: GET

Gibt alle Dienststellen zurück, auf welche die Benutzerkennung Zugriff hat.

Request Query Parameter
Parameter Wert Beschreibung
full boolean

true : vollständige Daten zur Dienststelle zurückgeben

false : Daten in Kurzform zurückgeben - Default (nicht Logo, Kurzbeschreibung, Langbeschreibung, Behördenzuordnungen, Gebäudezuordnungen)

page integer (>= 0)

0-basierter Index der anzuzeigenden Teilseite / Teilmenge

default: 0

min: 0

max: [positive Ganzahl] = Menge aller gefundenen Dienststellen - 1

size integer (>= 1)

Anzahl der Dienststellen pro Teilseite / Teilmenge

default: 100

min: 1

max: 100

Response HTTP-Header

Im Response werden maximal 100 Dienststellen pro Anfrage zurückgegeben, auf welche die Benutzerkennung Zugriff hat. Folgende Response HTTP-Header liefern Informationen zur Gesamtzahl der Dienststellen und zum Paging-Kontext:

Header Beschreibung
X-Total-Count

Anzahl aller gefundenen Dienststellen (positive Ganzzahl)
Link

Paging-Kontext: URL zur ersten, nächsten, vorherigen und letzten Teilseite.

Muster :

Link: <URL>; rel="[first|next|prev|last]"[,]

Beispiel: (* zur besseren Lesbarkeit mehrzeilig)

<https://www.baybw-services.bayern.de/rest/allgemein/v3/dienststellen?full=false&page=1&size=10>; rel="next",
<https://www.baybw-services.bayern.de/rest/allgemein/v3/dienststellen?full=false&page=4&size=10>; rel="last",
<https://www.baybw-services.bayern.de/rest/allgemein/v3/dienststellen?full=false&page=0&size=10>; rel="first"

/rest/allgemein/v3/dienststellen/{dienststellenschluessel}

Methode: GET

Gibt die Dienststelle(n) bzw. Außenstellen mit dem angegebenen Dienststellenschlüssel zurück. Der Dienststellenschlüssel ist ein 7-stelliger numerischer Schlüssel, der bayerische Behörden im Dienststellenverzeichnis eindeutig identifiziert.

Das Bayerische Landesamt für Statistik und Datenverarbeitung hat z.B. den Dienststellenschlüssel 0308106. Seine Außenstellen haben den gleichen Dienststellenschlüssel, ergänzt durch eine laufende Nummer von 1 bis n. Die Hauptdienststelle selbst hat die laufende Nummer 0.

Request Query Parameter

keine

/rest/allgemein/v3/dienststellen/{dienststellenschluessel}/leistungen

Methode: GET

Gibt die Leistungen der Dienststelle mit dem angegebenen Dienststellenschlüssel zurück.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

/rest/allgemein/v3/dienststellen/{dienststellenschluessel}/formulare

Methode: GET

Gibt die Formulare der Dienststelle mit dem angegebenen Dienststellenschlüssel zurück.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).
D.h. dass auch Formulare einer "Regionalen Ergänzung" der angegebenen Gemeinde in der Response enthalten sind.

gruppiertNachLeistungen boolean

true (Default): Es werden Leistungen zurückgeliefert, die die zugeordneten Formulare beinhalten, somit können sie gegliedert angezeigt werden.

false: Es werden Formulare zurückgeliefert, die eine Liste von Leistungen (denen sie zugeordnet sind) mitführen.

/rest/allgemein/v3/dienststellen/{dienststellenschluessel}/leistungsbeschreibungen

Methode: GET

Gibt die Leistungsbeschreibungen der Dienststelle mit dem angegebenen Dienststellenschlüssel zurück.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

mitRegionalenErgaenzungen boolean

true: Regionale Ergänzungen zu Leistungsbeschreibungen werden ausgeliefert, und zwar nur solche, für die die Dienststelle mit dem angegebenen Dienststellenschlüssel redaktionell zuständig ist ("eigene" regionale Ergänzungen).

Die "gemeindekennziffer" spielt für die Auswahl der passenden regionalen Ergänzungen hier keine Rolle, weil sie nur auf die Dienststelle bezogen sind.

false (Default): Es werden keine regionalen Ergänzungen bei den Leistungsbeschreibungen geliefert.

mitZustaendigkeiten boolean

true: Es werden auch die zuständigen Stellen geliefert.

Dabei werden nur Behörden / Organisationseinheiten berücksichtigt, die zur Dienststelle mit dem angegebenen "dienststellenschluessel" gehören, also die Dienststelle selbst, ihre Außenstellen und die Organisationseinheiten im Organigramm dieser Dienststelle oder ihrer Außenstellen).

Die angegebene "gemeindekennziffer" spielt hier für die Ermittlung der zuständigen Behörden keine Rolle. Sie kann auch weggelassen werden.

false (Default): Es werden keine zuständigen Stellen geliefert.

/rest/allgemein/v3/dienststellen/{dienststellenschluessel}/lebenslagen

Methode: GET

Gibt die Lebenslagen für die Dienststelle mit dem angegebenen Dienststellenschlüssel zurück.

Lebenslagen sind entweder Oberkategorien oder Unterkategorien:

Man sollte daraus eine zweistufige Navigation erstellen, denn Leistungen der Dienststelle sind nur den Unterkategorien zugeordnet.

Von allen grundsätzlich verfügbaren Lebenslagen werden nur die ausgeliefert, denen eine Leistung der angegebenen Dienststelle zugeordnet ist. Die dazugehörigte Oberkategorie wird natürlich mitgeliefert, damit der zweistufige Navigationsaufbau erstellt werden kann.

Die Sortierung erfolgt nach der ID der Lebenslage (von 100001000 bis 35001305), so dass das Ergebnis unmittelbar sequentiell verarbeitet werden kann.

Fehlernachrichten

/rest/allgemein/v3/behoerden

Methode: GET

Gibt alle Behörden zurück, auf welche die Benutzerkennung Zugriff hat.

Request Query Parameter
Parameter Wert Beschreibung
full boolean

true : vollständige Daten zur Behörde zurückgeben

false : Daten in Kurzform zurückgeben - Default (nicht Logo, Kurzbeschreibung, Langbeschreibung, Behördenzuordnungen, Gebäudezuordnungen)

page integer (>= 0)

0-basierter Index der anzuzeigenden Teilseite / Teilmenge

default: 0

min: 0

max: [positive Ganzahl] = Menge aller gefundenen Behörden - 1

size integer (>= 1)

Anzahl der Behörden pro Teilseite / Teilmenge

default: 100

min: 1

max: 100

Response HTTP-Header

Im Response werden maximal 100 Behörden pro Anfrage zurückgegeben, auf welche die Benutzerkennung Zugriff hat. Folgende Response HTTP-Header liefern Informationen zur Gesamtzahl der Behörden und zum Paging-Kontext:

Header Beschreibung
X-Total-Count

Anzahl aller gefundenen Behörden (positive Ganzzahl)
Link

Paging-Kontext: URL zur ersten, nächsten, vorherigen und letzten Teilseite.

Muster :

Link: <URL>; rel="[first|next|prev|last]"[,]

Beispiel: (* zur besseren Lesbarkeit mehrzeilig)

<https://www.baybw-services.bayern.de/rest/allgemein/v3/behoerden?full=false&page=1&size=10>; rel="next",
<https://www.baybw-services.bayern.de/rest/allgemein/v3/behoerden?full=false&page=4&size=10>; rel="last",
<https://www.baybw-services.bayern.de/rest/allgemein/v3/behoerden?full=false&page=0&size=10>; rel="first"

/rest/allgemein/v3/behoerden/{behoerde-id}

Methode: GET

Gibt eine vollständige Repräsentation der Behörde mit der angegebenen Id zurück. Die Id der Behörde ist ein eindeutiger numerischer Wert, den Sie aus einem vorherigen Webservice-Zugriff als Referenz-Id erhalten haben.

Request Query Parameter
Parameter Wert Beschreibung
sicheresKontaktformular boolean

true : der Link auf das "Sichere Kontaktformular" der Behörde wird ggf. mitgeliefert

false : Ohne Ermittlung des Links auf das "Sichere Kontaktformular" - Default

/rest/allgemein/v3/behoerden/{behoerde-id}/gebaeude/{gebaeude-id}

Methode: GET

Gibt eine Repräsentation eines Gebäudes der Behörde mit der angegebenen Id zurück. Die Id der Behörde und des Gebäudes sind eindeutige numerische Werte, die Sie aus einem vorherigen Webservice-Zugriff als Referenz-Ids erhalten haben.

Request Query Parameter

keine

/rest/allgemein/v3/behoerden/{behoerde-id}/leistungen

Methode: GET

Gibt eine Liste aller Leistungen zurück, die der Behörde mit der angegebenen Id zugeordnet sind. Die Id der Behörde ist ein eindeutiger numerischer Wert, den Sie aus einem vorherigen Webservice-Aufruf als Referenz-Id erhalten haben

Request Query Parameter
Parameter Wert Beschreibung
nurDirekteLeistungszuordnungen boolean

true : nur Leistungen die der Behörde direkt zugeordnet sind

false : Leistungen die der Behörde direkt zugeordnet sind und solche, die einer nachgeordneten Organsationseinheit zugeordnet sind (=geerbte Leistungszuordnungen)

/rest/allgemein/v3/behoerden/{behoerde-id}/abgegebene-leistungen

Methode: GET

Gibt eine Liste aller Leistungen zurück, die eine Behörde (z.B. die Regierung von Unterfranken) an eine andere Behörde des gleichen Behördentyps (z.B. eine andere Bezirksregierung) abgegeben hat.

Derartige Sonderzuständigkeiten gibt es im Bereich der Bezirksregierungen z.B. im Bereich der Luftüberwachung und auf anderen Gebieten.

Die Id der Behörde, die die Leistungen abgegeben hat, ist ein eindeutiger numerischer Wert. Derzeit ist dieser Endpunkt nur für den Bereich der sieben bayerischen Bezirksregierungen anwendbar.

Die anfragende Benutzerkennung muss lesenden Zugriff auf die Behörde mit der angefragten Id haben, sonst wird ein entsprechender Fehlerhinweis (siehe unter Fehlernachrichten) zurückgegeben.

Request Query Parameter

keine

Fehlernachrichten

/rest/allgemein/v3/behoerden/{behoerde-id}/gebaeude/{gebaeude-id}/ansprechpartner/{ansprechpartner-id}

Methode: GET

Gibt eine Repräsentation des Ansprechpartners mit der angegebenen Id zurück. Der Ansprechpartner gehört zur Behörde mit der angegeben Id und dem Gebäude mit der angegebenen Id. Die Id der Behörde, des Gebäudes und des Ansprechpartners sind eindeutige numerische Werte, die Sie aus einem vorherigen Webservice-Aufruf als Referenz-Ids erhalten haben.

Request Query Parameter

keine

/rest/allgemein/v3/behoerden/{behoerde-id}/ansprechpartner

Methode: GET

Gibt die Ansprechpartner der Behörde mit der angegebenen Id zurück.

Request Query Parameter

keine

/rest/allgemein/v3/ansprechpartner

Methode: GET

Gibt eine Liste aller Ansprechpartner zurück, auf welche die Benutzerkennung Zugriff hat.

Pro Ansprechpartner wird per Voreinstellung nur eine Repräsentation mit wichtigen Merkmalen zurückgegeben. Um alle verfügbaren Daten eines Ansprechpartners abzurufen, setzen Sie bitte den Query Parameter full=true oder benutzen Sie die URL /rest/allgemein/v3/ansprechpartner/{ansprechpartner-id} mit der die Daten zu einem bestimmten Ansprechpartner vollständig zurückgegeben werden.

Request Query Parameter
Parameter Wert Beschreibung
full boolean

false : Daten in Kurzform zurückgeben - Default

true : vollständige Daten zum Ansprechpartner zurückgeben (auch Logo, Kommunikationsdaten, Sprechzeiten und direkt zugeordnete Leistungen)

/rest/allgemein/v3/ansprechpartner/{ansprechpartner-id}

Methode: GET

Gibt eine vollständige Repräsentation des Ansprechpartner mit der angegebenen Id zurück (auch Logo, Kommunikationsdaten, Sprechzeiten und direkt zugeordnete Leistungen). Die Id des Ansprechpartners ist ein eindeutiger numerischer Wert, den Sie aus einem vorherigen Webservice-Aufruf als Referenz-Id erhalten haben.

Request Query Parameter

keine

/rest/allgemein/v3/ansprechpartner/{ansprechpartner-id}/leistungen

Methode: GET

Gibt eine Liste der Leistungen zurück, die dem Ansprechpartner mit der angegebenen Id zugeordnet sind. Die Id des Ansprechpartners ist ein eindeutiger numerischer Wert, den Sie aus einem vorherigen Webservice-Aufruf als Referenz-Id erhalten haben.

Request Query Parameter
Parameter Wert Beschreibung
nurDirekteLeistungszuordnungen boolean

true : nur Leistungen die dem Ansprechpartner direkt zugeordnet sind

false : Leistungen die dem Ansprechpartner direkt zugeordnet sind und solche, die seiner/seinen Organsationseinheit(en) zugeordnet sind (=geerbte Leistungszuordnungen)

/rest/allgemein/v3/leistungen

Methode: GET

Gibt eine Liste aller Leistungen zurück.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

/rest/allgemein/v3/leistungen/{leistung-id}

Methode: GET

Gibt die Leistung mit der angegebenen Id zurück.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

/rest/allgemein/v3/leistungsbeschreibungen

Methode: GET

Gibt eine Liste aller Leistungenbeschreibungen ohne Zuständigkeiten-Block zurück.

Zur Abfrage der Zuständigkeiten sind

notwendig.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

mitRegionalenErgaenzungen boolean

true: Es werden regionale Ergänzungen passend zur gemeindekennziffer bei den Leistungsbeschreibungen geliefert.

false (Default): Es werden keine regionale Ergänzungen bei den Leistungsbeschreibungen geliefert.

/rest/allgemein/v3/leistungsbeschreibungen/{leistung-id}

Methode: GET

Gibt die Leistungbeschreibung mit der angegebenen Id zurück.

Falls der Parameter gemeindekennziffer angegeben ist und einen gültigen 8-stelligen Gemeindeschlüssel enthält (z.B. 09262000 für Landshut), wird daraus eine Lokalisierung (PLZ und Ort, z.B. 84028 Landshut) abgeleitet. Es werden die für die Leistung an diesem Ort zuständigen Behörden zurückgegeben.

Ebenso werden auch die regionalen Ergänzungen zurückgegeben, die zur abgeleiteten Lokalisierung passen.

Falls der Parameter gemeindekennziffer nicht angegeben oder nicht gültig ist, kann keine Lokalisierung (PLZ und Ort) abgeleitet werden. Auch zuständige Behörden und regionale Ergänzungen können dann nicht geliefert werden.

Request Query Parameter
Parameter Wert Beschreibung
gemeindekennziffer string

8-stelliger Amtlicher Gemeindeschlüssel eines Ortes in Bayern, für den der Response lokalisiert werden soll (z.B. 09162000 für München).

mitRegionalenErgaenzungen boolean

true (Default): Es werden regionale Ergänzungen passend zur gemeindekennziffer bei den Leistungsbeschreibungen geliefert.

false: Es werden keine regionale Ergänzungen bei den Leistungsbeschreibungen geliefert.

sicheresKontaktformular boolean

true : der Link auf das "Sichere Kontaktformular" der Behörde (im Bereich "Zuständigkeiten") wird ggf. mitgeliefert

false : Ohne Ermittlung des Links auf das "Sichere Kontaktformular" - Default

behoerdenAnsprechpartnerZuordnungen string

DIREKTBEVORZUGT (Default): Die der angegebenen Leistung direkt zugeordneten Ansprechpartner werden vorrangig ermittelt und zurückgegeben. Sind im jeweiligen Gebäude keine Mitarbeiter der Behörde direkt zuständig, werden alle Mitarbeiter dieser Behörde/Organisationseinheit in diesem Gebäude ausgegeben.

DIREKT: Nur direkte Ansprechpartner werden ausgegeben.

ALLE: Alle Mitarbeiter im jeweiligen Gebäude der zuständigen Behörde werden ermittelt und ausgegeben.

NEIN: Es werden KEINE Ansprechpartner ausgegeben.

/rest/allgemein/v3/lebenslagen

Methode: GET

Gibt eine Liste aller Lebenslagen zurück.

Request Query Parameter
Parameter Wert Beschreibung
leistungenZugeordnet boolean

true : nur Lebenslagen mit Leistungszuordnungen werden geliefert

false : alle Lebenslagen werden geliefert

Hinweis : Lebenslagen sind in Ober- und Unterkategorien gegliedert. Beispielsweise gibt es die Oberkategorie "10000100 - Geburt" mit den Unterkategorien "10000102 - Vor der Geburt", "10000103 - Nach der Geburt" usw. Wenn es in der Unterkategorie "10000102 - Vor der Geburt" Leistungszuordnungen gibt, dann wird auch die Oberkategorie "10000100 - Geburt" geliefert.

/rest/allgemein/v3/lebenslagen/{lebenslage-id}

Methode: GET

Gibt die Leistung mit der angegebenen Id zurück.

Request Query Parameter

keine