certigo/backend/openapi.yaml

openapi: 3.0.3
info:
  title: Certigo Addon API
  description: API für die Verwaltung von Spaces, FQDNs und Certificate Signing Requests (CSRs)
  version: 1.0.0
  contact:
    name: Certigo Addon

servers:
  - url: http://localhost:8080/api
    description: Local development server

paths:
  /health:
    get:
      summary: System Health Check
      description: Prüft den Systemstatus des Backends
      tags:
        - System
      responses:
        '200':
          description: System ist erreichbar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  
  /stats:
    get:
      summary: Statistiken abrufen
      description: Ruft Statistiken über die Anzahl der Spaces, FQDNs und CSRs ab
      tags:
        - System
      responses:
        '200':
          description: Statistiken erfolgreich abgerufen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'

  /spaces:
    get:
      summary: Alle Spaces abrufen
      description: Ruft eine Liste aller Spaces ab
      tags:
        - Spaces
      responses:
        '200':
          description: Liste der Spaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Space'
    
    post:
      summary: Space erstellen
      description: Erstellt einen neuen Space
      tags:
        - Spaces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpaceRequest'
      responses:
        '201':
          description: Space erfolgreich erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Space'
        '400':
          description: Ungültige Anfrage

  /spaces/{id}:
    delete:
      summary: Space löschen
      description: Löscht einen Space. Wenn der Space FQDNs enthält, muss der Parameter deleteFqdns=true gesetzt werden.
      tags:
        - Spaces
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: deleteFqdns
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Wenn true, werden alle FQDNs des Spaces mitgelöscht
      responses:
        '200':
          description: Space erfolgreich gelöscht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: Space nicht gefunden
        '409':
          description: Space enthält noch FQDNs

  /spaces/{id}/fqdns/count:
    get:
      summary: FQDN-Anzahl abrufen
      description: Ruft die Anzahl der FQDNs für einen Space ab
      tags:
        - FQDNs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Anzahl der FQDNs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'

  /spaces/{id}/fqdns:
    get:
      summary: Alle FQDNs eines Spaces abrufen
      description: Ruft alle FQDNs für einen Space ab
      tags:
        - FQDNs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Liste der FQDNs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FQDN'
        '404':
          description: Space nicht gefunden
    
    post:
      summary: FQDN erstellen
      description: Erstellt einen neuen FQDN innerhalb eines Spaces
      tags:
        - FQDNs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFQDNRequest'
      responses:
        '201':
          description: FQDN erfolgreich erstellt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FQDN'
        '400':
          description: Ungültige Anfrage
        '404':
          description: Space nicht gefunden
        '409':
          description: FQDN existiert bereits in diesem Space
    
    delete:
      summary: Alle FQDNs eines Spaces löschen
      description: Löscht alle FQDNs eines Spaces
      tags:
        - FQDNs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Alle FQDNs erfolgreich gelöscht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'

  /spaces/{id}/fqdns/{fqdnId}:
    delete:
      summary: FQDN löschen
      description: Löscht einen einzelnen FQDN
      tags:
        - FQDNs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: fqdnId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: FQDN erfolgreich gelöscht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '404':
          description: FQDN nicht gefunden

  /fqdns:
    delete:
      summary: Alle FQDNs global löschen
      description: Löscht alle FQDNs aus allen Spaces. Erfordert confirm=true Query-Parameter.
      tags:
        - FQDNs
      parameters:
        - name: confirm
          in: query
          required: true
          schema:
            type: boolean
          description: Muss true sein, um die Operation auszuführen
      responses:
        '200':
          description: Alle FQDNs erfolgreich gelöscht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: Bestätigung erforderlich

  /csrs:
    delete:
      summary: Alle CSRs global löschen
      description: Löscht alle CSRs aus allen Spaces. Erfordert confirm=true Query-Parameter.
      tags:
        - CSRs
      parameters:
        - name: confirm
          in: query
          required: true
          schema:
            type: string
          description: Muss "true" sein, um die Operation auszuführen
          example: "true"
      responses:
        '200':
          description: Alle CSRs erfolgreich gelöscht
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          description: Bestätigung erforderlich

  /spaces/{spaceId}/fqdns/{fqdnId}/csr:
    post:
      summary: CSR hochladen
      description: Lädt einen CSR (Certificate Signing Request) im PEM-Format hoch
      tags:
        - CSRs
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: fqdnId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - csr
                - spaceId
                - fqdn
              properties:
                csr:
                  type: string
                  format: binary
                  description: CSR-Datei im PEM-Format
                spaceId:
                  type: string
                  description: ID des Spaces
                fqdn:
                  type: string
                  description: Name des FQDNs
      responses:
        '201':
          description: CSR erfolgreich hochgeladen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CSR'
        '400':
          description: Ungültige Anfrage oder ungültiges CSR-Format
        '404':
          description: Space oder FQDN nicht gefunden
    
    get:
      summary: CSR(s) abrufen
      description: Ruft CSR(s) für einen FQDN ab. Mit latest=true wird nur der neueste CSR zurückgegeben.
      tags:
        - CSRs
      parameters:
        - name: spaceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: fqdnId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: latest
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Wenn true, wird nur der neueste CSR zurückgegeben
      responses:
        '200':
          description: CSR(s) erfolgreich abgerufen
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CSR'
                  - type: array
                    items:
                      $ref: '#/components/schemas/CSR'
        '404':
          description: FQDN nicht gefunden

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: "ok"
        message:
          type: string
          example: "Backend ist erreichbar"
        time:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
    
    StatsResponse:
      type: object
      properties:
        spaces:
          type: integer
          example: 5
        fqdns:
          type: integer
          example: 12
        csrs:
          type: integer
          example: 7
    
    Space:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          example: "Mein Space"
        description:
          type: string
          example: "Beschreibung des Spaces"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
    
    CreateSpaceRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          example: "Mein Space"
        description:
          type: string
          example: "Beschreibung des Spaces"
    
    FQDN:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "660e8400-e29b-41d4-a716-446655440000"
        spaceId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        fqdn:
          type: string
          example: "example.com"
        description:
          type: string
          example: "Beschreibung des FQDN"
        createdAt:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
    
    CreateFQDNRequest:
      type: object
      required:
        - fqdn
      properties:
        fqdn:
          type: string
          example: "example.com"
        description:
          type: string
          example: "Beschreibung des FQDN"
    
    Extension:
      type: object
      properties:
        id:
          type: string
          example: "2.5.29.37"
        oid:
          type: string
          example: "2.5.29.37"
        name:
          type: string
          example: "X509v3 Extended Key Usage"
        critical:
          type: boolean
          example: false
        value:
          type: string
          example: "301406082b0601050507030106082b06010505070302"
        description:
          type: string
          example: "TLS Web Server Authentication\n                    TLS Web Client Authentication"
        purposes:
          type: array
          items:
            type: string
          example: ["TLS Web Server Authentication", "TLS Web Client Authentication"]
    
    CSR:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "770e8400-e29b-41d4-a716-446655440000"
        fqdnId:
          type: string
          format: uuid
          example: "660e8400-e29b-41d4-a716-446655440000"
        spaceId:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        fqdn:
          type: string
          example: "example.com"
        csrPem:
          type: string
          example: "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----"
        subject:
          type: string
          example: "CN=example.com"
        publicKeyAlgorithm:
          type: string
          example: "RSA"
        signatureAlgorithm:
          type: string
          example: "SHA256-RSA"
        keySize:
          type: integer
          example: 2048
        dnsNames:
          type: array
          items:
            type: string
          example: ["example.com", "www.example.com"]
        emailAddresses:
          type: array
          items:
            type: string
          example: ["admin@example.com"]
        ipAddresses:
          type: array
          items:
            type: string
          example: ["192.168.1.1"]
        uris:
          type: array
          items:
            type: string
          example: ["https://example.com"]
        extensions:
          type: array
          items:
            $ref: '#/components/schemas/Extension'
        createdAt:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00Z"
    
    MessageResponse:
      type: object
      properties:
        message:
          type: string
          example: "Operation erfolgreich"
    
    CountResponse:
      type: object
      properties:
        count:
          type: integer
          example: 5
    
    DeleteResponse:
      type: object
      properties:
        message:
          type: string
          example: "Alle FQDNs erfolgreich gelöscht"
        deletedCount:
          type: integer
          example: 5

  securitySchemes:
    {}:
      type: http
      scheme: none