certigo/docs/API_CHEATSHEET.md

# 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)