REST-API – Authentifizierung, Antwortumschlag und OpenAPI

Überblick

JSON-Endpunkte für externe Systeme (index.php?route=api/gruppe/ressource.methode). Jeder Ressourcen-Controller hat eine Methode openapi(): array; daraus entsteht die zusammengeführte Beschreibung.

Authentifizierung

• Der Schlüssel kommt im Header X-Oc-Api-Key oder abwärtskompatibel im POST-Feld api_key; die Endpunkte masterdata und subscription/order akzeptieren ihn nicht als GET-Parameter, der Explorer schon.
• Auflösung: api/auth::getUserByApiKey() → user_api_key (status=1) verknüpft mit dem aktiven Framework-Benutzer → Benutzer, Gruppe, Benutzername. Fehlt die Tabelle user_api_key, ist jeder Schlüssel ungültig.
• Die Endpunkte prüfen das Funktionsrecht des Schlüsselinhabers mit den Schlüsseln der Admin-Routen (canActionForUser).

Eingabe und Antwort

• apiInput(): GET-Parameter, roher Body (JSON, sonst urlencoded) und POST-Felder zusammengeführt; spätere überschreiben frühere.
• apiOut() → dlbtjson->restEnvelope(). Bei Erfolg das eigene JSON des Endpunkts mit HTTP 200, Struktur unverändert. Bei Fehler success:false, error (eine Meldung), error_code, bei Feldvalidierung zusätzlich error_fields.
• HTTP-Status aus dem Code (statusFor()): VALIDATION_ERROR 422, BAD_REQUEST 400, UNAUTHORIZED 401, PERMISSION_DENIED 403, NOT_FOUND 404, CONFLICT 409, DB_QUERY_ERROR, UNCAUGHT_EXCEPTION, PHP_FATAL_ERROR 500; ohne Code VALIDATION_ERROR.
• Jeder Methodenrumpf steht in try/catch; debug_message käme nur mit dem Recht debug hinzu, das auf der Catalog-Seite mangels Rechteverwaltung immer falsch ist.
• Protokollierung: erfolgreiche und abgewiesene Aufrufe im Systemprotokoll (Kanäle api/company, api/addressmaster, api/bankaccountmaster).

OpenAPI und Dokumentation

Bekannte Einschränkungen

• Die Endpunktbeschreibungen des Admin-OpenAPI-Dokuments sind Dokumentationsplatzhalter („Implementation status: Insufficient data to verify“).
• Die Endpunkte von Explorer und Admin-Dokumentation sind in den Seeds des Rechtekatalogs nicht eingeordnet.