Session-API v1¶

Die Session-API ist die erweiterte, authentifizierte Schnittstelle des Verwaltungs-RIS. Sie ergänzt die OParl-API je Kommune, die ausschließlich öffentliche Daten anonym liefert, um nicht-öffentliche Daten für berechtigte Nutzer und um das Einreichen von Anträgen durch Fraktionen.

Basis-URL: https://<host>/api/v1/session/<kommune>/ – <kommune> ist der Kurzname (Slug) des Mandanten.

Listen liefern data und meta (total, limit, offset, authenticated). limit ist 1 bis 200, Standard 100.

Authentifizierung¶

API-Token werden in Session unter Einstellungen → API-Tokens angelegt (siehe Einreichungs-Zugänge für Fraktionen) und im Header mitgeschickt:

Authorization: Bearer <token>

Ein Token gehört zu genau einer Kommune. Seine Flags heißen Öffentliche Sitzungen lesen, Öffentliche Vorlagen lesen und Anträge einreichen. Ein Token liest nur öffentliche Daten – nicht-öffentliche Sitzungen, Vorlagen, Texte und interne Notizen liefert die API nie an ein Token, unabhängig von den Flags: Ein Token gehört zu keiner Person, deren Berechtigung für Nicht-Öffentliches geprüft wäre. Optional lässt sich das Token auf IP-Adressen beschränken und mit einem Ratenlimit je Minute versehen; bei Überschreitung antwortet die API mit 429 und Retry-After.

Angemeldete Nutzer des Session-RIS nutzen die API mit ihrer Browser-Sitzung und ihren Rollenrechten (nur lesend); nur so sind nicht-öffentliche Daten erreichbar. Ohne Token und ohne Sitzung sind nur öffentliche Daten sichtbar.

Antrag einreichen¶

POST /api/v1/session/musterstadt/applications/submit/
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Spielplatz Musterstraße",
  "application_type": "motion",
  "justification": "…",
  "resolution_proposal": "…",
  "submitter_name": "Fraktion Beispiel",
  "submitter_email": "fraktion@example.org",
  "target_organization_id": "…",
  "is_urgent": false
}

Antwort 201 mit id, reference (Aktenzeichen) und status. Zulässige application_type-Werte: motion, inquiry, resolution, urgent, amendment, other. Das Work-Portal nutzt genau diesen Weg, siehe Anträge digital einreichen.

Fehlerformat¶

Fehler kommen als application/problem+json nach RFC 9457:

{
  "type": "https://docs.mandari.de/api/probleme/keine-berechtigung",
  "title": "Keine Berechtigung",
  "status": 403,
  "detail": "Dieses Token darf keine Anträge einreichen.",
  "instance": "/api/v1/session/musterstadt/applications/submit/",
  "request_id": "3f2b…"
}

Validierungsfehler (422) tragen zusätzlich errors mit Feld, Meldung und Typ. Die request_id entspricht dem Antwort-Header X-Request-ID; Betreiber finden sie in den Server-Logs wieder (siehe Logging und Tracing).

Ablösung der alten Pfade¶

Der Einstiegspunkt /session/<kommune>/api/ und die OParl-API je Kommune bleiben. Unterschiede beim Umstieg: