Phase 1: OpenAPI-Contract für Backend-API definieren

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks

#323 Phase 2: Backend in Go implementieren

customable/claude-mem

Reference

customable/claude-mem#322

jack commented

2026-01-26 08:26:22 +00:00

Owner

Ziel

OpenAPI 3.1 Spec für alle Backend-Endpoints generieren/erstellen, sodass das Backend austauschbar wird, ohne Hooks, Worker oder UI anzupassen.

Warum zuerst

Die Hooks kommunizieren bereits über HTTP REST mit dem Backend - das ist der natürliche Trennpunkt. Eine saubere API-Spec macht das Backend austauschbar und verbessert gleichzeitig die Dokumentation.

Aufgaben

1. Bestandsaufnahme der API-Surface

Alle 175+ Endpoints dokumentieren (Pfad, Method, Request/Response-Types)
WebSocket-Protokoll dokumentieren (Message-Types, Auth-Flow)
SSE-Event-Types dokumentieren

2. OpenAPI-Spec erstellen

Schemas für alle Request/Response-Bodies
Path-Parameter und Query-Parameter
Auth-Schema (Bearer Token, Localhost-Bypass)
Error-Responses (AppError, BadRequestError, etc.)
WebSocket-Protokoll als AsyncAPI-Spec (optional)

3. Validierung

Spec gegen aktuelle Endpoints testen (Request/Response-Matching)
Types aus Spec generieren und mit packages/types vergleichen
CI-Check: Spec bleibt synchron mit Implementation

Relevante Endpoint-Gruppen

Gruppe	Endpoints	Priorität
Hooks (`/api/hooks/*`)	~16	Hoch - Hauptinterface
Health (`/api/health/*`)	~6	Hoch - Monitoring
Data (`/api/data/*`)	~85	Mittel - UI
Search (`/api/search/*`)	~4	Mittel - MCP + UI
Stream (`/api/stream/*`)	~2	Hoch - SSE
Workers (`/api/workers/*`)	~7	Mittel - Federation
WebSocket (`/ws`)	Message-Protokoll	Hoch - Worker-Kommunikation

Ergebnis

openapi.yaml im Repo-Root
Optional: AsyncAPI-Spec für WebSocket/SSE
TypeScript-Types werden aus Spec generiert (statt manuell gepflegt)
Go-Server-Stubs können aus Spec generiert werden

Teil von

#321 Backend-Migration: Inkrementeller Wechsel von Node/TypeScript zu Go

## Ziel OpenAPI 3.1 Spec für alle Backend-Endpoints generieren/erstellen, sodass das Backend austauschbar wird, ohne Hooks, Worker oder UI anzupassen. ## Warum zuerst Die Hooks kommunizieren bereits über HTTP REST mit dem Backend - das ist der natürliche Trennpunkt. Eine saubere API-Spec macht das Backend austauschbar und verbessert gleichzeitig die Dokumentation. ## Aufgaben ### 1. Bestandsaufnahme der API-Surface - [ ] Alle 175+ Endpoints dokumentieren (Pfad, Method, Request/Response-Types) - [ ] WebSocket-Protokoll dokumentieren (Message-Types, Auth-Flow) - [ ] SSE-Event-Types dokumentieren ### 2. OpenAPI-Spec erstellen - [ ] Schemas für alle Request/Response-Bodies - [ ] Path-Parameter und Query-Parameter - [ ] Auth-Schema (Bearer Token, Localhost-Bypass) - [ ] Error-Responses (AppError, BadRequestError, etc.) - [ ] WebSocket-Protokoll als AsyncAPI-Spec (optional) ### 3. Validierung - [ ] Spec gegen aktuelle Endpoints testen (Request/Response-Matching) - [ ] Types aus Spec generieren und mit `packages/types` vergleichen - [ ] CI-Check: Spec bleibt synchron mit Implementation ## Relevante Endpoint-Gruppen | Gruppe | Endpoints | Priorität | |--------|-----------|-----------| | Hooks (`/api/hooks/*`) | ~16 | Hoch - Hauptinterface | | Health (`/api/health/*`) | ~6 | Hoch - Monitoring | | Data (`/api/data/*`) | ~85 | Mittel - UI | | Search (`/api/search/*`) | ~4 | Mittel - MCP + UI | | Stream (`/api/stream/*`) | ~2 | Hoch - SSE | | Workers (`/api/workers/*`) | ~7 | Mittel - Federation | | WebSocket (`/ws`) | Message-Protokoll | Hoch - Worker-Kommunikation | ## Ergebnis - `openapi.yaml` im Repo-Root - Optional: AsyncAPI-Spec für WebSocket/SSE - TypeScript-Types werden aus Spec generiert (statt manuell gepflegt) - Go-Server-Stubs können aus Spec generiert werden ## Teil von #321 Backend-Migration: Inkrementeller Wechsel von Node/TypeScript zu Go

jack referenced this issue

2026-01-26 08:26:24 +00:00

Phase 2: Backend in Go implementieren #323

jack added the

labels

2026-01-26 08:26:25 +00:00

jack added a new dependency

2026-01-26 08:26:36 +00:00

jack closed this issue

2026-01-26 08:32:44 +00:00