# Certigo Addon API Cheatsheet ## Base URL ``` http://localhost:8080/api ``` Alle Endpunkte unterstützen CORS und akzeptieren OPTIONS-Requests für Preflight-Checks. --- ## System & Statistics ### GET /health Prüft den Systemstatus des Backends. **Response:** ```json { "status": "ok", "message": "Backend ist erreichbar", "time": "2024-01-15T10:30:00Z" } ``` **Beispiel:** ```bash curl http://localhost:8080/api/health ``` --- ### GET /stats Ruft Statistiken über die Anzahl der Spaces, FQDNs und CSRs ab. **Response:** ```json { "spaces": 5, "fqdns": 12, "csrs": 7 } ``` **Beispiel:** ```bash curl http://localhost:8080/api/stats ``` --- ## Spaces ### GET /spaces Ruft alle Spaces ab. **Response:** ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Mein Space", "description": "Beschreibung des Spaces", "createdAt": "2024-01-15T10:30:00Z" } ] ``` **Beispiel:** ```bash curl http://localhost:8080/api/spaces ``` --- ### POST /spaces Erstellt einen neuen Space. **Request Body:** ```json { "name": "Mein Space", "description": "Beschreibung des Spaces" } ``` **Response:** `201 Created` ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Mein Space", "description": "Beschreibung des Spaces", "createdAt": "2024-01-15T10:30:00Z" } ``` **Beispiel:** ```bash curl -X POST http://localhost:8080/api/spaces \ -H "Content-Type: application/json" \ -d '{ "name": "Mein Space", "description": "Beschreibung des Spaces" }' ``` --- ### DELETE /spaces/{id} Löscht einen Space. **Query Parameters:** - `deleteFqdns` (optional, boolean): Wenn `true`, werden alle FQDNs des Spaces mitgelöscht. **Response:** `200 OK` ```json { "message": "Space erfolgreich gelöscht" } ``` **Fehler:** - `409 Conflict`: Space enthält noch FQDNs (nur wenn `deleteFqdns` nicht `true` ist) **Beispiele:** ```bash # Space ohne FQDNs löschen curl -X DELETE http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000 # Space mit allen FQDNs löschen curl -X DELETE "http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000?deleteFqdns=true" ``` --- ### GET /spaces/{id}/fqdns/count Ruft die Anzahl der FQDNs für einen Space ab. **Response:** ```json { "count": 5 } ``` **Beispiel:** ```bash curl http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns/count ``` --- ## FQDNs ### GET /spaces/{id}/fqdns Ruft alle FQDNs für einen Space ab. **Response:** ```json [ { "id": "660e8400-e29b-41d4-a716-446655440000", "spaceId": "550e8400-e29b-41d4-a716-446655440000", "fqdn": "example.com", "description": "Beschreibung des FQDN", "createdAt": "2024-01-15T10:30:00Z" } ] ``` **Beispiel:** ```bash curl http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns ``` --- ### POST /spaces/{id}/fqdns Erstellt einen neuen FQDN innerhalb eines Spaces. **Request Body:** ```json { "fqdn": "example.com", "description": "Beschreibung des FQDN" } ``` **Response:** `201 Created` ```json { "id": "660e8400-e29b-41d4-a716-446655440000", "spaceId": "550e8400-e29b-41d4-a716-446655440000", "fqdn": "example.com", "description": "Beschreibung des FQDN", "createdAt": "2024-01-15T10:30:00Z" } ``` **Fehler:** - `409 Conflict`: FQDN existiert bereits in diesem Space (case-insensitive) **Beispiel:** ```bash curl -X POST http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns \ -H "Content-Type: application/json" \ -d '{ "fqdn": "example.com", "description": "Beschreibung des FQDN" }' ``` --- ### DELETE /spaces/{id}/fqdns/{fqdnId} Löscht einen einzelnen FQDN. **Response:** `200 OK` ```json { "message": "FQDN erfolgreich gelöscht" } ``` **Beispiel:** ```bash curl -X DELETE http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns/660e8400-e29b-41d4-a716-446655440000 ``` --- ### DELETE /spaces/{id}/fqdns Löscht alle FQDNs eines Spaces. **Response:** `200 OK` ```json { "message": "Alle FQDNs erfolgreich gelöscht", "deletedCount": 5 } ``` **Beispiel:** ```bash curl -X DELETE http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns ``` --- ### DELETE /fqdns?confirm=true Löscht alle FQDNs aus allen Spaces. **WICHTIG:** Erfordert `confirm=true` Query-Parameter. **Query Parameters:** - `confirm` (required, boolean): Muss `true` sein, um die Operation auszuführen. **Response:** `200 OK` ```json { "message": "Alle FQDNs erfolgreich gelöscht", "deletedCount": 12 } ``` **Beispiel:** ```bash curl -X DELETE "http://localhost:8080/api/fqdns?confirm=true" ``` --- ## CSRs (Certificate Signing Requests) ### POST /spaces/{spaceId}/fqdns/{fqdnId}/csr Lädt einen CSR (Certificate Signing Request) im PEM-Format hoch. **Request:** `multipart/form-data` - `csr` (file, required): CSR-Datei im PEM-Format (.pem oder .csr) - `spaceId` (string, required): ID des Spaces - `fqdn` (string, required): Name des FQDNs **Response:** `201 Created` ```json { "id": "770e8400-e29b-41d4-a716-446655440000", "fqdnId": "660e8400-e29b-41d4-a716-446655440000", "spaceId": "550e8400-e29b-41d4-a716-446655440000", "fqdn": "example.com", "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----", "subject": "CN=example.com", "publicKeyAlgorithm": "RSA", "signatureAlgorithm": "SHA256-RSA", "keySize": 2048, "dnsNames": ["example.com", "www.example.com"], "emailAddresses": ["admin@example.com"], "ipAddresses": ["192.168.1.1"], "uris": ["https://example.com"], "extensions": [ { "id": "2.5.29.37", "oid": "2.5.29.37", "name": "X509v3 Extended Key Usage", "critical": false, "value": "301406082b0601050507030106082b06010505070302", "description": "TLS Web Server Authentication\n TLS Web Client Authentication", "purposes": ["TLS Web Server Authentication", "TLS Web Client Authentication"] } ], "createdAt": "2024-01-15T10:30:00Z" } ``` **Beispiel:** ```bash curl -X POST http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns/660e8400-e29b-41d4-a716-446655440000/csr \ -F "csr=@/path/to/certificate.csr" \ -F "spaceId=550e8400-e29b-41d4-a716-446655440000" \ -F "fqdn=example.com" ``` --- ### GET /spaces/{spaceId}/fqdns/{fqdnId}/csr Ruft CSR(s) für einen FQDN ab. **Query Parameters:** - `latest` (optional, boolean): Wenn `true`, wird nur der neueste CSR zurückgegeben. Standard: alle CSRs. **Response (ohne `latest`):** `200 OK` ```json [ { "id": "770e8400-e29b-41d4-a716-446655440000", "fqdnId": "660e8400-e29b-41d4-a716-446655440000", "spaceId": "550e8400-e29b-41d4-a716-446655440000", "fqdn": "example.com", "csrPem": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----", "subject": "CN=example.com", "publicKeyAlgorithm": "RSA", "signatureAlgorithm": "SHA256-RSA", "keySize": 2048, "dnsNames": ["example.com"], "emailAddresses": [], "ipAddresses": [], "uris": [], "extensions": [...], "createdAt": "2024-01-15T10:30:00Z" } ] ``` **Response (mit `latest=true`):** `200 OK` ```json { "id": "770e8400-e29b-41d4-a716-446655440000", ... } ``` **Beispiele:** ```bash # Alle CSRs abrufen curl http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns/660e8400-e29b-41d4-a716-446655440000/csr # Nur neuesten CSR abrufen curl "http://localhost:8080/api/spaces/550e8400-e29b-41d4-a716-446655440000/fqdns/660e8400-e29b-41d4-a716-446655440000/csr?latest=true" ``` --- ## Extension Details CSR Extensions werden automatisch geparst und in menschenlesbarem Format zurückgegeben: ### Bekannte Extension-Namen: - `X509v3 Key Usage` - `X509v3 Subject Alternative Name` - `X509v3 Basic Constraints` - `X509v3 Extended Key Usage` - `X509v3 CRL Distribution Points` - `X509v3 Certificate Policies` - `X509v3 Authority Key Identifier` - `X509v3 Subject Key Identifier` ### Extended Key Usage Werte: - `TLS Web Server Authentication` - `TLS Web Client Authentication` - `Code Signing` - `E-mail Protection` - `Time Stamping` - `OCSP Signing` - `IPsec End System` - `IPsec Tunnel` - `IPsec User` --- ## HTTP Status Codes - `200 OK`: Erfolgreiche Anfrage - `201 Created`: Ressource erfolgreich erstellt - `400 Bad Request`: Ungültige Anfrage - `404 Not Found`: Ressource nicht gefunden - `409 Conflict`: Konflikt (z.B. FQDN existiert bereits) - `500 Internal Server Error`: Serverfehler --- ## Fehlerbehandlung Bei Fehlern wird eine Fehlermeldung im Response-Body zurückgegeben: ```json { "error": "Fehlermeldung" } ``` Oder als Plain-Text: ``` Fehlermeldung ``` --- ## CORS Alle Endpunkte unterstützen CORS mit folgenden Headern: - `Access-Control-Allow-Origin: *` - `Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS` - `Access-Control-Allow-Headers: Content-Type` --- ## Hinweise 1. **UUIDs**: Alle IDs sind UUIDs im Format `550e8400-e29b-41d4-a716-446655440000` 2. **Timestamps**: Alle Timestamps sind im RFC3339-Format (ISO 8601) 3. **FQDN-Validierung**: FQDNs werden case-insensitive verglichen 4. **CSR-Format**: CSRs müssen im PEM-Format vorliegen 5. **Cascading Deletes**: Beim Löschen eines Spaces werden alle zugehörigen FQDNs und CSRs automatisch gelöscht (ON DELETE CASCADE)