API Konventionen

API-Konventionen

Einstieg

Im Entwicklungsbetrieb stehen OpenAPI und Swagger UI unter http://localhost:8000/docs sowie das Schema unter http://localhost:8000/openapi.json bereit.

Routen und Verträge

• Haupt-REST-Endpunkte liegen unter /api.
• Platform-Admin-Endpunkte liegen getrennt unter /api/admin.
• Kollaboration verwendet /api/ws/protocols/{public_id}.
• Öffentliche Abgabebox-Endpunkte gehören ins separate Abgabebox-Backend.
• Ein- und Ausgabe werden mit Pydantic-Schemas typisiert.
• Externe Referenzen verwenden öffentliche IDs, nie interne Integer-IDs.

Authentifizierung

Kunden- und Platform-Admin-Login sind getrennte Systeme mit eigenen Tabellen, Cookies und Secrets. Ein Endpunkt darf niemals implizit beide Sitzungstypen akzeptieren.

Mandantenendpunkte prüfen neben der Anmeldung immer den aktuellen Tenant und die erforderliche Rolle. Rollenprüfung nur im Frontend ist keine Sicherheitsgrenze.

Statuscodes und Fehler

• 200: erfolgreiche Abfrage/Änderung mit Response-Body
• 201: neu angelegte Ressource
• 204: erfolgreiche Aktion ohne Body
• 400/422: ungültige Eingabe
• 401: keine gültige Sitzung
• 403: angemeldet, aber nicht berechtigt
• 404: Ressource im erlaubten Scope nicht vorhanden
• 409: fachlicher Konflikt oder konkurrierende Änderung
• 429: Rate-Limit
• 500: unerwarteter interner Fehler

Fehler verwenden das FastAPI-übliche detail-Feld. Keine Stacktraces, SQL-Fragmente, Secrets oder internen IDs an Clients zurückgeben.

Listen und Pagination

Listenendpunkte verwenden skip und limit und eine stabile Sortierung. Neue unbegrenzte Endpunkte sind zu vermeiden. Aggregationen wie laufende Salden werden über den gesamten Datenbestand berechnet, nicht nur über die aktuell geladene Seite.

Nebenläufigkeit

Für veränderliche Ressourcen müssen Konflikte sichtbar behandelt werden. Fachliche Eindeutigkeit wird durch DB-Constraints abgesichert; Quotas, Bussen und vergleichbare Race-anfällige Abläufe benötigen Locks oder atomare Operationen. Erwartbare Konflikte geben 409 zurück.

Datei-Endpunkte

Dateiannahme prüft serverseitig Grösse, erlaubten Typ, Magic Bytes, Dateinamen/Pfad, Tenant-Quota und Scanstatus. Der vom Browser angegebene Content-Type allein genügt nie.

Frontend-Zugriff

• Browser: relative /api/...-URLs und credentials: include.
• Server-Komponenten: backendFetchWithSession, damit Cookies weitergereicht werden.
• Kein eigenes Auth-Redirect bei einem reinen Netzwerkfehler.
• Mutationen behandeln ApiError nach Fehlerkategorie.
• Abgabebox-Client bleibt wegen anderer Sicherheitsanforderungen separat.

WebSocket

Der Kollaborationskanal überträgt Presence, Locks und Änderungsbenachrichtigungen, nicht die alleinige Persistenz. REST bleibt die massgebliche Speicherung. Neue Nachrichtentypen benötigen server- und clientseitige Validierung, Reconnect-Verhalten und Tests.

Checkliste für neue Endpunkte

• Route, Methode und Statuscode passen zur Aktion.
• Request- und Response-Schema sind explizit.
• Auth-System, Tenant und Rolle werden geprüft.
• Nur öffentliche IDs verlassen das Backend.
• Listen sind paginiert und stabil sortiert.
• Konflikte und Nebenläufigkeit sind berücksichtigt.
• Audit-Log ist für sicherheits-/geschäftsrelevante Aktionen ergänzt.
• Positiv-, Validierungs-, Rollen- und Cross-Tenant-Test existieren.