Mind-o-Mat/docs/openapi.yaml

openapi: 3.1.0
info:
  title: Mind-o-Mat Notes API
  version: 1.0.0
  description: |
    HTTP-API für die Mind-o-Mat PWA zum Lesen/Schreiben von Notizen im Vault.
    Wird vom Vite-Dev-Server-Plugin (siehe `webapp/vite.config.ts`) bereitgestellt
    und vom Service Worker für Background-Sync genutzt.
  contact:
    name: Mind-o-Mat
    url: https://git.orfel.de/Jannik/Mind-o-Mat
  license:
    name: MIT

servers:
  - url: http://localhost:5173
    description: Lokaler Dev-Server (Vite)
  - url: https://vault.example.com
    description: Production-Deployment (eigene Domain)

tags:
  - name: notes
    description: Notizen lesen und schreiben
  - name: sync
    description: gitea-Sync triggern

security:
  - bearerAuth: []

paths:
  /api/notes:
    get:
      tags: [notes]
      summary: Liste aller Notiz-IDs
      description: |
        Gibt eine Liste der Notiz-IDs in den 4 Standard-Verzeichnissen zurück
        (00_Inbox/, 10_Wiki/Seiten/, 01_Daily/, 20_Projekte/).
        Verarbeitet/Problemfaelle werden NICHT gelistet.
      security: []
      responses:
        '200':
          description: Liste der Notiz-IDs
          content:
            application/json:
              schema:
                type: object
                required: [notes]
                properties:
                  notes:
                    type: array
                    items:
                      type: string
                      description: Relative ID (z. B. "10_Wiki/Seiten/Kaffee.md")
                      example: "10_Wiki/Seiten/Kaffee.md"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/notes/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Relative Notiz-ID (URL-encoded)
        schema:
          type: string
        example: "10_Wiki/Seiten/Kaffee.md"
    get:
      tags: [notes]
      summary: Einzelne Notiz lesen
      security: []
      responses:
        '200':
          description: Notiz gefunden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteData'
        '404':
          description: Notiz nicht gefunden
          content:
            text/plain:
              schema:
                type: string
                example: "Not found"
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags: [notes]
      summary: Notiz speichern (Update oder Create)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  description: Vollstaendiger Markdown-Inhalt inkl. Frontmatter
                  example: |
                    ---
                    title: Mein Thema
                    created: 2026-09-05
                    ---

                    # Inhalt
      responses:
        '200':
          description: Notiz gespeichert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /api/sync:
    post:
      tags: [sync]
      summary: Sync zu gitea triggern
      description: |
        Ruft `mindomat sync` als Subprozess auf. Blockiert, bis der Sync fertig ist.
        Wird vom Service Worker Background-Sync aufgerufen.
      security: []
      responses:
        '200':
          description: Sync erfolgreich
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Sync fehlgeschlagen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncResult'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Optional. Wenn in der Vite-Plugin-Konfiguration `authToken` gesetzt ist,
        müssen alle API-Calls einen `Authorization: Bearer <token>`-Header mitsenden.
        Token-Format: `<timestamp>.<hmac-sha256-hex>`.

  schemas:
    NoteData:
      type: object
      required: [id, content, frontmatter, lastModified]
      properties:
        id:
          type: string
          description: Relative Notiz-ID
          example: "10_Wiki/Seiten/Kaffee.md"
        content:
          type: string
          description: Vollstaendiger Markdown-Inhalt
        frontmatter:
          type: object
          description: Geparste Frontmatter-Felder
          additionalProperties: true
          example:
            title: "Kaffee"
            created: "2026-09-05"
        lastModified:
          type: string
          format: date-time
          description: ISO-Timestamp

    SyncResult:
      type: object
      required: [ok, message]
      properties:
        ok:
          type: boolean
          description: War der Sync erfolgreich?
          example: true
        message:
          type: string
          description: Sync-Output oder Fehlermeldung
          example: "git push erfolgreich."

  responses:
    Unauthorized:
      description: Authentifizierung fehlt oder ungueltig
      content:
        text/plain:
          schema:
            type: string
            example: "Authorization-Header fehlt"
    ServerError:
      description: Interner Server-Fehler
      content:
        text/plain:
          schema:
            type: string
            example: "Konnte Datei nicht schreiben: EACCES"