nick.adam/certigo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity
Files
3ea0ebae1b096fed79d51755b71795372d202f3b
certigo/API_CHEATSHEET.md
Nick Adam c0e2df2430 upload all
2025-11-20 13:29:13 +01:00

9.1 KiB
Raw Blame History

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:

{
  "status": "ok",
  "message": "Backend ist erreichbar",
  "time": "2024-01-15T10:30:00Z"
}

Beispiel:

curl http://localhost:8080/api/health

GET /stats

Ruft Statistiken über die Anzahl der Spaces, FQDNs und CSRs ab.

Response:

{
  "spaces": 5,
  "fqdns": 12,
  "csrs": 7
}

Beispiel:

curl http://localhost:8080/api/stats

Spaces

GET /spaces

Ruft alle Spaces ab.

Response:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Mein Space",
    "description": "Beschreibung des Spaces",
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

Beispiel:

curl http://localhost:8080/api/spaces

POST /spaces

Erstellt einen neuen Space.

Request Body:

{
  "name": "Mein Space",
  "description": "Beschreibung des Spaces"
}

Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Mein Space",
  "description": "Beschreibung des Spaces",
  "createdAt": "2024-01-15T10:30:00Z"
}

Beispiel:

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

{
  "message": "Space erfolgreich gelöscht"
}

Fehler:

  • 409 Conflict: Space enthält noch FQDNs (nur wenn deleteFqdns nicht true ist)

Beispiele:

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

{
  "count": 5
}

Beispiel:

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:

[
  {
    "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:

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:

{
  "fqdn": "example.com",
  "description": "Beschreibung des FQDN"
}

Response: 201 Created

{
  "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:

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

{
  "message": "FQDN erfolgreich gelöscht"
}

Beispiel:

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

{
  "message": "Alle FQDNs erfolgreich gelöscht",
  "deletedCount": 5
}

Beispiel:

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

{
  "message": "Alle FQDNs erfolgreich gelöscht",
  "deletedCount": 12
}

Beispiel:

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

{
  "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:

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

[
  {
    "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

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  ...
}

Beispiele:

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

{
  "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)