{
  "openapi": "3.0.3",
  "info": {
    "title": "KeyHelp Kunden-API",
    "description": "Multi-Tenant Customer API Gateway für KeyHelp Webhosting und Server Management. Ermöglicht Kunden den Zugriff auf ihre eigenen Ressourcen.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "/",
      "description": "Aktueller Webspace Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "KeyHelp-Benutzername und KeyHelp-Passwort"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer Token aus /api/v1/auth/login"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Optionaler API-Key"
      }
    }
  },
  "security": [
    { "BasicAuth": [] },
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/api": {
      "get": {
        "summary": "API Gateway Info & Status",
        "security": [],
        "responses": {
          "200": { "description": "Dienst-Informationen und Endpunkte" }
        }
      }
    },
    "/api/health": {
      "get": {
        "summary": "Health-Check",
        "security": [],
        "responses": {
          "200": { "description": "Status OK" }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "summary": "Login mit KeyHelp Benutzerdaten (erzeugt Bearer Token)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "password"],
                "properties": {
                  "username": { "type": "string", "example": "mein_keyhelp_user" },
                  "password": { "type": "string", "example": "mein_geheimes_passwort" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Login erfolgreich, Token zurückgegeben" },
          "401": { "description": "Ungültige Anmeldedaten" }
        }
      }
    },
    "/api/v1/account": {
      "get": {
        "summary": "Eigenes Kundenprofil abrufen",
        "responses": {
          "200": { "description": "Kundenprofildaten" },
          "401": { "description": "Nicht authentifiziert" }
        }
      }
    },
    "/api/v1/account/stats": {
      "get": {
        "summary": "Ressourcen-Verbrauch und Quotas abfragen (Speicherplatz, Traffic, DBs, E-Mail)",
        "responses": {
          "200": { "description": "Statistiken und Quotas" }
        }
      }
    },
    "/api/v1/domains": {
      "get": {
        "summary": "Alle Domains und Subdomains des Kunden auflisten",
        "responses": {
          "200": { "description": "Domain-Liste" }
        }
      },
      "post": {
        "summary": "Neue Subdomain oder Domain anlegen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain"],
                "properties": {
                  "domain": { "type": "string", "example": "api.meinedomain.de" },
                  "php_version": { "type": "string", "example": "8.2" },
                  "target_dir": { "type": "string", "example": "/www/api" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Domain erfolgreich angelegt" }
        }
      }
    },
    "/api/v1/domains/{id}": {
      "get": {
        "summary": "Details einer Domain abrufen",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Domain-Details" } }
      },
      "put": {
        "summary": "Domain-Einstellungen aktualisieren",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Domain aktualisiert" } }
      },
      "delete": {
        "summary": "Domain löschen",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Domain gelöscht" } }
      }
    },
    "/api/v1/dns/zones": {
      "get": {
        "summary": "Alle eigenen DNS-Zonen auflisten",
        "responses": { "200": { "description": "Liste der DNS-Zonen" } }
      }
    },
    "/api/v1/dns/{domain_id}/records": {
      "get": {
        "summary": "DNS-Records einer Domain auflisten",
        "parameters": [{ "name": "domain_id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": { "200": { "description": "Liste aller DNS-Einträge" } }
      },
      "post": {
        "summary": "Neuen DNS-Record hinzufügen",
        "parameters": [{ "name": "domain_id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["type", "value"],
                "properties": {
                  "host": { "type": "string", "example": "_acme-challenge" },
                  "type": { "type": "string", "example": "TXT" },
                  "value": { "type": "string", "example": "challenge_token_string" },
                  "ttl": { "type": "integer", "example": 300 }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Record erstellt" } }
      }
    },
    "/api/v1/acme/dns-challenge": {
      "post": {
        "summary": "ACME Certbot DNS-01 Challenge TXT-Record setzen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain", "token"],
                "properties": {
                  "domain": { "type": "string", "example": "meinedomain.de" },
                  "token": { "type": "string", "example": "certbot_acme_validation_hash" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Challenge-Record gesetzt" } }
      },
      "delete": {
        "summary": "ACME Certbot Challenge TXT-Record nach Zertifikatserstellung bereinigen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain"],
                "properties": {
                  "domain": { "type": "string", "example": "meinedomain.de" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Challenge bereinigt" } }
      }
    },
    "/api/v1/mailboxes": {
      "get": {
        "summary": "E-Mail-Postfächer des Kunden auflisten",
        "responses": { "200": { "description": "Liste der Mailboxen" } }
      },
      "post": {
        "summary": "Neues E-Mail-Postfach erstellen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["address", "password"],
                "properties": {
                  "address": { "type": "string", "example": "kontakt@meinedomain.de" },
                  "password": { "type": "string", "example": "GeheimesPasswort123!" },
                  "quota_mb": { "type": "integer", "example": 1024 }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Postfach erstellt" } }
      }
    },
    "/api/v1/email-forwards": {
      "get": {
        "summary": "E-Mail-Weiterleitungen auflisten",
        "responses": { "200": { "description": "Liste der Weiterleitungen" } }
      },
      "post": {
        "summary": "Neue Weiterleitung einrichten",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["source", "destination"],
                "properties": {
                  "source": { "type": "string", "example": "alias@meinedomain.de" },
                  "destination": { "type": "string", "example": "ziel@andereseite.de" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Weiterleitung erstellt" } }
      }
    },
    "/api/v1/databases": {
      "get": {
        "summary": "MySQL-Datenbanken auflisten",
        "responses": { "200": { "description": "Liste der Datenbanken" } }
      },
      "post": {
        "summary": "Neue MySQL-Datenbank anlegen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["database_name"],
                "properties": {
                  "database_name": { "type": "string", "example": "app_db" },
                  "description": { "type": "string", "example": "Produktivdatenbank" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Datenbank angelegt" } }
      }
    },
    "/api/v1/database-users": {
      "get": {
        "summary": "Datenbank-Benutzer auflisten",
        "responses": { "200": { "description": "Liste der DB-Benutzer" } }
      },
      "post": {
        "summary": "Neuen Datenbank-Benutzer anlegen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "password"],
                "properties": {
                  "username": { "type": "string", "example": "db_user" },
                  "password": { "type": "string", "example": "SicheresDbPasswort123!" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "DB-Benutzer angelegt" } }
      }
    },
    "/api/v1/ftp-users": {
      "get": {
        "summary": "FTP-Benutzer auflisten",
        "responses": { "200": { "description": "Liste der FTP-Benutzer" } }
      },
      "post": {
        "summary": "Neuen FTP-Benutzer anlegen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["username", "password"],
                "properties": {
                  "username": { "type": "string", "example": "ftp_kunde" },
                  "password": { "type": "string", "example": "SicheresFtpPasswort123!" },
                  "directory": { "type": "string", "example": "/www" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "FTP-Benutzer erstellt" } }
      }
    },
    "/api/v1/certificates": {
      "get": {
        "summary": "SSL-Zertifikate auflisten",
        "responses": { "200": { "description": "Liste der SSL-Zertifikate" } }
      }
    },
    "/api/v1/certificates/lets-encrypt": {
      "post": {
        "summary": "Let's Encrypt Zertifikat via KeyHelp beantragen",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id_domain"],
                "properties": {
                  "id_domain": { "type": "integer", "example": 10 }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Zertifikatsanfrage gestartet" } }
      }
    }
  }
}