Modulentwicklung (APInterface)

Zentraler Einstieg für Entwickler und KI-Agenten — https://apinterface.com/docs/modulentwicklung (Architektur, Mandanten, Integration, Zugänge, Repo-Anweisungen).

Architektur

Platform / Core / Modul — jeweils eigenes Repo und eigene Version; Releases unveränderlich aktivieren (z. B. Symlink), keine produktiven In-Place-Edits.
Integration nur über Core-Schnittstellen: src/moduleManifest.js, src/index.js, optional src/views/body.ejs. Keine Secrets im Git; DB u. ä. serverseitig (z. B. mysql_config_editor).
vServer typisch unter /opt/apps/apinterface/ (platform, core, modules, shared) — andere Projekte auf dem Host nicht beeinträchtigen.

Mandanten und Nutzer

Der Core ist mandantenorientiert: Arbeit erfolgt im Kontext einer Firma (company); Nutzer können mehreren Firmen zugeordnet sein und die aktive Firma wechseln.
Pro Firma hat ein Nutzer eine oder mehrere Rollen (roleKey); Rechte und UI hängen von dieser Kombination ab (u. a. Platform-Admin vs. Firmenkontext).
Module erscheinen anhand von appKey/appKeys im Manifest nur, wenn die Firma die passenden Apps aktiviert hat; schreibende Setup-Routen sind im Core an Firmen-Superuser gebunden — eigene Modul-Logik muss dieselbe Mandanten- und Rechtevorstellung respektieren (keine Daten über Firmengrenzen vermischen).

Modul-Repo & Discovery

Eigenes Repo, Version in package.json; Deploy per Tag/SSH wie in der Platform dokumentiert.
Der Core findet Releases unter den Scan-Roots: …/current/src/moduleManifest.js oder …/src/moduleManifest.js. Bei mehreren Treffern zählt die höhere Modulversion.
Release-Metadaten (JSON): /schema/module.manifest.json — ergänzt, ersetzt nicht das UI-Manifest.

Zugangsdaten (`credentialSlots`)

Im Manifest optional credentialSlots: pro Eintrag id (snake_case), label, kind (secret | password | text | choice), required, optional description. Bei choice zusätzlich options als Liste { value, label }.
Optional credentialProbe pro Slot: z. B. { "kind": "mysql", "mysql": { "hostSlot": "mysql_host", "portSlot": "mysql_port", "userSlot": "mysql_user", "passwordSlot": "mysql_password", "databaseSlot": "mysql_database" } } — Button „MySQL-Verbindung testen“ und Protokolleinträge auf der App-Seite /apps/<appKey>/access.
Der Core speichert Werte verschlüsselt (Tab. company_app_credentials), Konfiguration unter /apps/<appKey>/access (nicht im Modul-Screen).
Module lesen serverseitig Klartext nur über getCompanyAppCredentials(companyId, appKey) aus src/lib/appCredentials.js — Pfad z. B. require(require("path").join(global.APINTERFACE_CORE_SRC, "lib/appCredentials")) (global.APINTERFACE_CORE_SRC setzt der Core in server.js).

HTTP-API (Core, Version 1)

Drittentwickler: ausführliche Einstiegsseite /docs/http-api-v1 (kanonisch https://apinterface.com/docs/http-api-v1) — OpenAPI, PAT, Scopes, Module, CORS.

Präfix /api/v1 — JSON. Öffentliche Meta-Endpunkte: GET /api/v1/health (inkl. coreVersion), GET /api/v1/meta/scopes, GET /api/v1/meta/build (kein Login).
PAT (Personal Access Token): Authorization: Bearer …; Token in der UI unter /settings/api-tokens (Firmen-Superuser) erzeugen; gebunden an Nutzer und Firma; Klartext nur einmal sichtbar.
GET/POST/DELETE /api/v1/account/tokens und GET /api/v1/account/tokens/{id}: Liste/Einzelobjekt mit Session (Superuser) oder Bearer api.tokens.read; anlegen/widerrufen mit Session+CSRF oder Bearer api.tokens.manage. GET /api/v1/account/audit/security (Security-Audit der Firma): Session oder Bearer api.audit.read, optional ?limit= (max. 200). Fehlerantworten: Header X-Request-Id und im JSON-Feld requestId. Optional CORS: API_CORS_ORIGINS. Maschinenlesbar: GET /api/v1/openapi.json (OpenAPI 3.0).
Module (opt-in): optional src/api/registerApiV1.js mit Export registerApiV1 — Routen unter /api/v1/modules/<manifest-id>/…; PAT-Scope api.modules.invoke. Im Manifest "httpApiV1": true; optional Objekt apiV1Module mit summary, documentationUrl, registerPath (siehe JSON-Schema).
Core-Liveness: GET /healthz. Rate-Limits, Audit-Tabelle und Session-Cookie-Optionen siehe Core-Release und .cursor/rules/apinterface-http-api.mdc.

KI-Anweisungen im Git-Repository

Diese Seite ist die kanonische Langfassung. Zusätzlich liegen im Repo kurze Anweisungen, die von Tools automatisch einbezogen werden können — immer zusammen mit diesem Link verwenden.

GitHub Copilot (Chat, Code Review, Cloud Agent): Datei .github/copilot-instructions.md im Repository-Root — siehe GitHub: Custom instructions. Im Core: apinterface-core/.github/copilot-instructions.md.
Cursor: Regeln unter .cursor/rules/*.mdc — siehe Cursor: Rules. Im Core: z. B. modulentwicklung.mdc (alwaysApply).
Meta-Workspace (gesammeltes Repo): StefanB80/apinterface/.github/copilot-instructions.md und .cursor/rules/apinterface-modulentwicklung.mdc.
Eigene Modul-Repos: dieselben Pfade nachziehen oder minimale Dateien anlegen, die auf diese URL und das Schema verweisen — Copilot/Cursor lesen nur das jeweils geöffnete Repo.

Für KI-Agenten (Copy)

Vollständige Doku: https://apinterface.com/docs/modulentwicklung
HTTP-API v1 (Drittentwickler): https://apinterface.com/docs/http-api-v1
APInterface: Platform/Core/Modul getrennt versioniert; keine Secrets im Repo.
Module: moduleManifest.js + index.js (+ optional body.ejs); appKeys; optional credentialSlots; optional httpApiV1 + apiV1Module + src/api/registerApiV1.js.
HTTP-API: /api/v1, meta/build, audit/security (api.audit.read), openapi.json, PAT Bearer, api.tokens.* / api.audit.read, Fehler-JSON requestId, X-CSRF-Token für Session-JSON, /settings/api-tokens.
Zugänge: /apps/<appKey>/access; Klartext nur serverseitig getCompanyAppCredentials.
Deploy: versionierte Releases. Repo-KI: .github/copilot-instructions.md, .cursor/rules/*.mdc (siehe Seite).
Schema: https://apinterface.com/schema/module.manifest.json