API Dokumentation

CharGraph API für STL-Generierung und Datenverarbeitung.

---

Übersicht

Die CharGraph API bietet Endpoints für:

• STL-Datei-Generierung aus Pattern-Strings
• 3D-Modell-Rendering mit OpenSCAD
• Asynchrone Job-Verarbeitung

Base URL: https://www.chargraph.de/api

---

Endpoints

POST /api/generate

Generiert eine STL-Datei aus einem Pattern-String.

Request:

POST /api/generate HTTP/1.1
Content-Type: application/json

{
  "pattern": "ES_IST_BALD...",
  "filename": "my-wordclock"
}

Request Body:

Response (Success):

{
  "status": "success",
  "job_id": "abc123",
  "download_url": "/api/download/abc123.stl",
  "processing_time": 12.5
}

Response (Error):

{
  "status": "error",
  "message": "Invalid pattern length",
  "code": "INVALID_PATTERN"
}

Status Codes:

• 200 OK - Erfolgreich generiert
• 400 Bad Request - Ungültige Eingabe
• 500 Internal Server Error - Server-Fehler
• 503 Service Unavailable - Server überlastet

---

GET /api/download/:filename

Lädt eine generierte STL-Datei herunter.

Request:

GET /api/download/my-wordclock.stl HTTP/1.1

Response:

Content-Type: application/sla
Content-Disposition: attachment; filename="my-wordclock.stl"

[STL Binary Data]

Status Codes:

• 200 OK - Datei gefunden
• 404 Not Found - Datei existiert nicht
• 410 Gone - Datei abgelaufen (nach 24h)

---

Verwendung

Mit JavaScript (Fetch API)

async function generateSTL(pattern, filename) {
    const response = await fetch('https://www.chargraph.de/api/generate', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ pattern, filename })
    });

    const data = await response.json();

    if (data.status === 'success') {
        // Download-Link öffnen
        window.location.href = data.download_url;
    } else {
        console.error('Fehler:', data.message);
    }
}

// Verwendung
const pattern = "ES_IST_BALD...";
generateSTL(pattern, "meine-uhr");

Mit Python

import requests

def generate_stl(pattern, filename):
    url = 'https://www.chargraph.de/api/generate'
    payload = {
        'pattern': pattern,
        'filename': filename
    }

    response = requests.post(url, json=payload)
    data = response.json()

    if data['status'] == 'success':
        # Download
        download_url = f"https://www.chargraph.de{data['download_url']}"
        stl_response = requests.get(download_url)

        with open(f'{filename}.stl', 'wb') as f:
            f.write(stl_response.content)

        print(f"✓ STL gespeichert: {filename}.stl")
    else:
        print(f"✗ Fehler: {data['message']}")

# Verwendung
pattern = "ES_IST_BALD..."
generate_stl(pattern, "meine-uhr")

Mit cURL

# STL generieren
curl -X POST https://www.chargraph.de/api/generate \
  -H "Content-Type: application/json" \
  -d '{"pattern":"ES_IST_BALD...","filename":"test"}' \
  | jq .

# STL herunterladen
curl -O https://www.chargraph.de/api/download/test.stl

---

Rate Limits

• 10 Requests pro Minute pro IP
• 100 Requests pro Tag pro IP

Bei Überschreitung:

{
  "status": "error",
  "message": "Rate limit exceeded",
  "retry_after": 60
}

---

Pattern-Format

Anforderungen

• Länge: Exakt 110 Zeichen
• Zeichen: A-Z, Umlaute (Ä, Ö, Ü), Unterstrich (_)
• Format: 10 Zeilen × 11 Spalten

Beispiel

ES_IST_BALD
FÜNFZEHNVOR
NACHHALB___
ZWEI_EINS__
DREIVIERELF
FÜNFSECHS__
SIEBENZWÖLF
ZEHNNEUN___
ACHT_______
UHR________

Als String:

ES_IST_BALDFÜNFZEHNVORNACHHALB___ZWEI_EINS__DREIVIEREFFFÜNFSECHS__SIEBENZWÖLFZEHNNEUN___ACHT_______UHR________

---

Fehler-Codes

---

Best Practices

1. Validierung vor API-Call

function validatePattern(pattern) {
    if (pattern.length !== 110) {
        return { valid: false, error: 'Länge muss 110 sein' };
    }

    if (!/^[A-ZÄÖÜ_]+$/.test(pattern)) {
        return { valid: false, error: 'Ungültige Zeichen' };
    }

    return { valid: true };
}

2. Timeout handling

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s

try {
    const response = await fetch(url, {
        signal: controller.signal,
        ...options
    });
} catch (error) {
    if (error.name === 'AbortError') {
        console.error('Request timeout');
    }
} finally {
    clearTimeout(timeoutId);
}

3. Retry-Logik

async function generateWithRetry(pattern, filename, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await generateSTL(pattern, filename);
        } catch (error) {
            if (i === maxRetries - 1) throw error;
            await new Promise(r => setTimeout(r, 1000 * (i + 1)));
        }
    }
}

---

Technische Details

OpenSCAD Rendering

Die API verwendet OpenSCAD für 3D-Rendering:

• Timeout: 120 Sekunden
• Font: WordclockFont2.ttf
• Ausgabe: Binary STL
• Größe: ~500 KB - 2 MB

Datei-Speicherung

• Speicherdauer: 24 Stunden
• Speicherort: /var/lib/models/
• Automatische Löschung: Nach 24h

---

Support

Bei API-Problemen:

• Prüfe Browser-Console für detaillierte Fehler
• Teste mit cURL für Netzwerk-Probleme
• Öffne ein GitHub Issue mit Request/Response

---

API Version: 1.0 Letzte Aktualisierung: Januar 2026