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://chargraph.wieland.org/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:

Parameter	Typ	Erforderlich	Beschreibung
pattern	string	Ja	Grid-Pattern (110 Zeichen)
filename	string	Ja	Dateiname ohne Extension

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://chargraph.wieland.org/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://chargraph.wieland.org/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://chargraph.wieland.org{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://chargraph.wieland.org/api/generate \
 -H "Content-Type: application/json" \
 -d '{"pattern":"ES_IST_BALD...","filename":"test"}' \
 | jq .

# STL herunterladen
curl -O https://chargraph.wieland.org/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

Code	Beschreibung
INVALID_PATTERN	Pattern-String ungültig
INVALID_LENGTH	Pattern nicht 110 Zeichen
INVALID_CHARS	Ungültige Zeichen im Pattern
INVALID_FILENAME	Dateiname ungültig
TIMEOUT	Rendering-Timeout (>120s)
OPENSCAD_ERROR	OpenSCAD Fehler
RATE_LIMIT	Rate Limit überschritten

---

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