URL Struktur sehr individuell

[ManAnRuck]

Beim Erstellen eines OpenApi-Schemas für OParl habe ich festgestellt, dass die URL-Struktur meiner Meinung nach nicht ganz korrekt implementiert ist.

Für Organisationen wird zwischen dem Identifikator organizations und der id ein zusätzliches Pfadelement eingefügt:

• Für Köln: https://buergerinfo.stadt-koeln.de/oparl/bodies/stadtverwaltung_koeln/organizations/at/9328 (mit /at/9328)
• Für Düsseldorf: https://ris-oparl.itk-rheinland.de/Oparl/bodies/0015/organizations/gr/400214 (mit /gr/400214)

Ich sehe derzeit keine Möglichkeit, dieses zusätzliche at oder gr in einer allgemein gültigen OpenApi-Definition zu berücksichtigen, was zu diesem Problem führt.

Könnt ihr dies bestätigen? Wäre es möglich, die Dokumentation anzupassen, um dieses Problem in Zukunft zu vermeiden?

[ManAnRuck]

Für Bonn ist mir jetzt gerade folgendes aufgefallen:
https://www.bonn.sitzung-online.de/oparl/bodies?id=1
statt:
https://www.bonn.sitzung-online.de/oparl/bodies/1

[levino]

Was ich total strange finde ist, wie die Filter implementiert sind.

https://nordstemmen.ratsinfomanagement.net/webservice/oparl/v1.1/body/1/organization/1-17/meeting

Das sollte meiner Meinung nach so Aussehen:

https://nordstemmen.ratsinfomanagement.net/webservice/oparl/v1.1/meeting?body=1&organization=1-17

Wieso ist das so komisch implementiert und wieso geht die Spec darauf gar nicht ein? Ich kann zumindest keine Angaben dazu finden, wie Filter oder Suche implementiert werden müssen und auch nichts dazu, dass dieses komische Nesting verboten ist.

[levino]

Für Bonn ist mir jetzt gerade folgendes aufgefallen: https://www.bonn.sitzung-online.de/oparl/bodies?id=1 statt: https://www.bonn.sitzung-online.de/oparl/bodies/1

Bonn hat einfach /bodies statt /body implementiert, oder wie? Ich lache mich kaputt. Gibt auch /organizations statt /organization.

[the-infinity]

Die Spec definiert gar keine Pfad-Struktur, sondern arbeitet vollständig mit internen Verlinkungen. Pfade und Filter sind daher eine Aufgabe der RIS. Bonn macht das auch sehr korrekt: https://www.bonn.sitzung-online.de/oparl/bodies ist die Bodies URL, darin ist https://www.bonn.sitzung-online.de/oparl/bodies?id=1 als Einzel-Body verlinkt.

Eine OpenAPI Spec wird daher nicht funktionieren, da jedes RIS das unterschiedlich macht.

Warum wir das gemacht haben? Wir haben einen Linked-Data-nahen Ansatz umgesetzt, wo die Aufgabe des Clients vor allem darin besteht, die interne Verlinkung zu folgen. Neben der Linked-Data-Kompatibilität hat es den Vorteil, dass technische Restriktionen der Ratsinfosysteme keine Rolle spielen.

[levino]

Interessant und danke für den Einblick. Die spec gibt aber klar vor, dass es einen /body-Endpunkt geben soll und keinen /bodies-Endpunkt. Zumindest verstehe ich die spec so. Das mit "plural vs singular" ist ja immer so eine debatte bei REST-APIs.

Das mit dem "Linked-Data-Ansatz" kann ich überhaupt nicht verstehen. Für mich ist der ganze Sinn dieser Spec, dass man einheitliche Queries auf alle Behörden-APIs abfeuern kann und immer vergleichbare Ergebnisse bekommt. Außerdem geht ein Server ja nicht so vor, dass er Ergebnisse ansieht und sich dann der Links darin bedient, die im logisch vorkommen um "weiterzusuchen". Das macht nur ein Mensch. Eine Applikation braucht sofort gewisse Informationen, gefiltert, paginiert, etc. Insofern wäre es wünschenswert, wenn die Spec deutlich härter formuliert wird und die einzelnen Anbieter nicht mehr frei entscheiden können, was ihnen so gefällt.

Um es noch einmal zu sagen: Das mit dem /bodies und /body ist für mich wirklich bestürzend schlecht gelöst. Wenn das wirklich erlaubt ist, ist die Spec kaputt.

[levino]

Meine Vermutung ist, dass die Firmen, die die Ratsinformationssysteme bauen, einfach die API entlang ihrer Frontend-Applikation entwickeln und notdürftig an die OParl-Specs anpassen. Was nicht für das eigene Frontend gebraucht wird, wird nicht implementiert. Wenn die eigenen Entwickler:innen keine große Erfahrung mit REST-APIs haben, wird einfach eine Art von API erfunden (filtering über Pfade, wie ich oben für Nordstemmen zeige, meiner Meinung nach inakzeptabler Missbrauch von REST). Leider bringt das Ergebnis dann sehr wenig, weil eine Software, die mit der OParl-Api von Gemeinde A funktioniert, überhaupt nicht für die Gemeinde B anzuwenden ist. Wo ist da bitte der gesellschaftliche Mehrwert?

[the-infinity]

Die Spec ist nicht darauf optimiert, eine generische API für Frontends zu bauen. Dafür sind die RIS auch viel zu langsam und ineffizient. Die API ist darauf optimiert, einen strukturierten Datenabruf möglich zu machen, um eine eigene Datenbank aufzubauen, und auf dieser eigenen Datenbank kann (und sollte!) man dann auch eine definierte API bauen. Wie gesagt, Linked Data Orientierung: wenn man die Linked Data Perspektive hat, ist die URL Struktur egal, das kann man durch sein eigenes Backend dann definieren.

Es gab damals durchaus die Initiative, auch Suchfilter zu spezifizieren. Das ist nur echt viel Arbeit, und da das alles ehrenamtlich geschehen ist, ist es nie passiert. Idee war damals, eine Datenbank mit vielen Städten aufzubauen, und dann basierend auf den real verfügbaren Daten sinnvolle Suchfilter zu spezifizieren.

Die RIS Hersteller haben übrigens einen erheblichen Aufwand durch OParl. In der RIS Welt sind APIs bislang eher selten, bis heute, es gibt selten eine saubere Trennung zwischen Backend und Frontend. Auch die internen Datenstrukturen der RIS sind deutlich unterschiedlich, so dass einige RIS sogar eine komplette parallele Datenbank aufgebaut haben, um OParl überhaupt irgendwie bereitzustellen. Ist halt leider so. Wir hatten damals die Grundsatzentscheidung getroffen, möglichst viel mit den RIS Herstellern zusammenzuarbeiten, um überhaupt Daten strukturiert aus dem System zu kriegen. Das unterscheidet uns von Popolo: Popolo ist erheblich restriktiver, was zur Folge hatte, dass alle uns bekannten Systeme nach Ende der Förderung eingestellt wurden, da der Pflegeaufwand schlicht zu groß war.

Die RIS Hersteller schaffen es übrigens regelmäßig nicht, selbst die einfachen Grundregeln von OParl einzuhalten, was ein erhebliches Problem für die Skalierung darstellt - und da sind wir noch ganz weit weg von fest definierten Pfaden. Das hat verschiedene Gründe, z.B. wissen wir von mindestens einem RIS, dass sie Strings zusammenfügen, statt eine JSON Library zu verwenden, und das endet halt immer wieder in invalidem JSON. Das ist das Level, auf dem wir uns da befinden. Leider. Wenn das für Dich alles nicht hinnehmbar ist, ist das total nachvollziehbar, aber nimms uns nicht übel: als kleines ehrenamtliches Team sind wir nicht geeignet, die Behörden-IT in Deutschland zu revolutionieren.

[levino]

Na, Euch nehme ich gar nichts übel. Ich nehme es den RIS-Hersteller-Firmen übel, dass sie so schlecht arbeiten (anders kann man das ja nicht beschreiben, was Du da erzählst) und vor allem, dass die Politiker:innen keine Gesetze verabschieden, die knallharte Vorschriften machen, unabhängig davon, was den Leuten, die sich da als RIS-Hersteller einen Lenz mit ihrer veralteten Technologie und womöglich mäßig kompetenten Mitarbeiter:innen machen wollen, gefällt.

Ich danke Dir sehr für die Zeit, mir so ausführlich zu antworten @the-infinity. Ist sehr interessant.

Leider halte ich Euren Ansatz aber so auch für erst einmal gescheitert. Es ist ja viel (viel!) zu teuer, für jede Behörde einen eigenen Scraper zu schreiben um die Daten (die sich ja ständig ändern bzw. erweitern) in eine eigene Datenbank zu kippen. Da ist es auch nicht viel aufwendiger, die API aus dem Frontend-Code zu reverse engineeren und man hätte sich den Standard fast sparen können. Tut mir sehr leid, das so brutal sagen zu müssen, ich kann mir gut vorstellen, wie viel Herzblut und Zeit darin steckt, aber so sieht es heute zumindest aus. Ich denke aber, mit der richtigen politischen Unterstützung kann man das noch fixen, indem eine OpenAPI spec geschrieben wird, die verbindlich für alle RIS in Deutschland wird.

[levino]

Was ich mich aber noch frage (und vielleicht ist es ja schon irgendwo beantwortet): Welches konkrete Szenario sollte der OParl-Standard denn ermöglichen? Diesen Linked-Data-Ansatz kenne ich aus meiner Arbeit überhaupt nicht, eben weil er nicht "sauber" auszuwerten ist (höchstens mit Scrapern und jeder Menge Heuristik / AI). Wo wird so etwas denn Eurer Meinung nach heute sinnvoll angeboten bzw. eingesetzt? Ich meine, so etwas entwickelt sich manchmal, wenn man eine eigene API für seine App schreibt (Facebook -> Landing Page -> Feed -> Post -> Comments -> Likes) oder solche Sachen, aber das ist halt Facebook und nicht ein Standard "für alle Social Networks". Außerdem haben die ja gerade wegen dieser Query-Hölle GraphQL entwickelt.

[levino]

Achso: Und die Idee, dass ich jetzt für das RIS der Gemeinde Nordstemmen ein React-Frontend baue, ist für mich absolut abwegig. Was soll das bringen? Und selbst wenn, würde mir ja irgendeine API reichen, wenn diese nicht einheitlich mit allen anderen ist, ist sie halt "unique" mit allen entsprechenden Kosten (Zeitaufwand und Einzelanpassung). Wolltet ihr wirklich nur, dass die Hersteller "API-first" arbeiten, damit ihr Eure eigenen Frontends bauen könnt? Ist es nicht viel interessanter, wenn man alle Daten aller Behörden mit Scripten aggregieren kann? Wieso wird dann so viel Fokus auf "den client" gelegt?

[the-infinity]

Da ist es auch nicht viel aufwendiger, die API aus dem Frontend-Code zu reverse engineeren und man hätte sich den Standard fast sparen können.

Mangels APIs ist es eher HTML Scraping. So hat das alles auch angefangen, offeneskoeln hatte am Anfang einen HTML Scraper. Da weder HTML noch Frontend-APIs stabil sind war das dann auch der Grund, OParl zu bauen: ein Datenmodell, wo man nicht alle paar Tage den Scraper anpassen muss, ist schon viel wert. Siehe auch das Schicksal von kleineAnfragen: https://kleineanfragen.de/info/stilllegung - das waren nur 16 Parlamente, und Maxi musste permanent hinterherbasteln. Bei 10k Kommunen in Deutschland ist das schlicht nicht leistbar.

Ich halte damit den Ansatz für nicht gescheitert: OParl hat sich als Quasi-Standard für Datenexporte in dem Bereich entwickelt, und wir wissen von mehreren Systemen, die OParl über RIS-Grenzen hinweg als Abrufsystem verwenden, statt jedes mal was individuelles Neues zu bauen. Er ist aber auch nicht so erfolgreich wie erhofft, weil die weiteren Schritte nie gegangen sind - OParl ist ja eigentlich erst der erste Schritt, wie du richtig erkennst. Aber die weiteren Schritte machen viel Arbeit, und die Idee, das irgendwo mit Menschen zu versehen, die für ihre Arbeit Geld bekommen, hat nie stattgefunden. Fördergelder funktionieren in dem Bereich nicht, weil die immer einen Eigenanteil erzwingen, was einen Businesscase voraussetzt - und offene Standards haben halt erstmal keinen Businesscase. Und bislang hat sich keine staatliche Entität dazu bereit erklärt, das in der nötigen technischen Tiefe weiterzutreiben. Wir Ehrenamtler haben mittlerweile alle Jobs, in denen wir so sehr eingebunden sind, dass wir es nicht schaffen, das in der nötigen Dimension weiter zu pushen. Es gibt mehrere Initiativen, die nächsten Schritte zu gehen, u.a. die Schweizer sind da gerade ziemlich aktiv. Aber es ist unfassbar mühsam und dauer erheblich länger als man sich das so vorstellt. In Deutschland gibt es gerade die Idee, OParl zu einem X-Standard zu machen, dann könnte man das als eine regulatorische Voraussetzung für alle Kommunen etablieren. Aber auch das ist alles viel (Gremien-)Arbeit. Feel free to do something about it. :)

[levino]

Was ist ein X-Standard?

[levino]

Ich verstehe übrigens den Hinweis und arbeite mich (bei den Grünen) mit solchen Themen ab, wo ich nur kann. Versuche dabei aber einen anderen Ansatz: Erst Gesetz, dann Implementierung. Sieht aber (noch) nicht danach aus, als wenn das zeitnah Früchte trägt :(