API-Methodik

Jede Umrechnung, die Convertitive ausliefert, ist zugleich ein JSON-Endpunkt unter /api/v1/. Die API ist seit FAZ 4 aktiv und liefert dieselben Faktoren und Formeln wie die Oberfläche — wenn ein Ergebnis auf der Seite korrekt ist, ist es auch aus der API korrekt.

Endpunkt-Design

Im REST-Stil. Der Pfad beschreibt die Ressource, der Query-String trägt die Parameter. Beispiele:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — alle Einheitenkategorien auflisten
• GET /api/v1/health/ — Dienstzustand (Verfügbarkeit + Version)

Keine POST-Bodies. Alle Eingaben sind Query-Parameter. Idempotent, cachebar, browserfreundlich.

Response-Hülle

Jede erfolgreiche Antwort hat dieselbe Form:

{
  "ok": true,
  "data": { /* endpoint-specific */ },
  "meta": { /* optional metadata: rateDate, factor, etc. */ }
}

Jede Fehlerantwort:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Human-readable explanation",
    "param": "from"
  }
}

Standard-HTTP-Statuscodes: 200 bei Erfolg, 400 bei Eingabefehlern, 404 bei unbekannten Kategorien/Einheiten, 500 nur, wenn wirklich etwas kaputtgegangen ist. Behandeln Sie 4xx nicht als wiederholbar.

CORS-Richtlinie

Access-Control-Allow-Origin: * auf jedem API-Endpunkt. Nutzen Sie ihn von jedem Origin aus, einschließlich der lokalen Entwicklung mit localhost. Kein Preflight nötig, da jede Anfrage ein GET ohne benutzerdefinierte Header ist — es gelten die Regeln für einfache Anfragen.

Keine Authentifizierung

Kein API-Schlüssel, kein OAuth, keine signierten Anfragen. Jeder Endpunkt ist anonym. Drei Gründe:

1. Die Daten sind nicht wertvoll genug, um sie zu sperren. Umrechnungsfaktoren für Einheiten sind gemeinfrei. EZB-Kurse werden von ~20 Diensten öffentlich nachveröffentlicht. Dafür Geld zu verlangen hieße, für die Daten anderer Geld zu verlangen.
2. Authentifizierung erzeugt Reibung für den dominanten Anwendungsfall. Ein Entwickler, der ein Feature testet, ein Student, der einen Hausaufgabenvergleich skriptet, ein Hobbyist, der einen Tracker baut — keiner von ihnen will sich erst registrieren.
3. Rate Limits regeln Missbrauch. Cloudflares Voreinstellungen plus die triviale Rechenkosten jeder Umrechnung bedeuten, dass jemand, der Convertitive scrapen will, die Daten schneller durch direktes Spiegeln des öffentlichen EZB-Feeds bekommt.

Versionierung

Das Präfix /api/v1/ ist beabsichtigt. Wenn sich die Response-Hülle oder die Fehlerform wesentlich ändert, wird daneben eine /api/v2/ ausgeliefert; v1 wird mindestens 12 Monate über den Start von v2 hinaus unterstützt.

Fehlerbehebungen und additive Änderungen (neue Endpunkte, neue optionale Felder in Antworten) werden fortlaufend ohne Versionssprung ausgeliefert.

Die API selbst ist sprachunabhängig — Zahlen, Einheitensymbole und ISO-Codes werden nicht übersetzt —, aber die redaktionellen Seiten, die sie dokumentieren, schon. Wir veröffentlichen lokalisierte Varianten unter sprachspezifischen Pfadpräfixen und signalisieren sie Suchmaschinen mit hreflang-Annotationen, die aus einem zentralen Übersetzungsregister generiert werden, sodass ein spanischer Leser von /es/methodology/api/ denselben JSON-Vertrag in seiner Sprache beschrieben bekommt.

Aktualität der Wechselkurse

Währungsendpunkte liefern den EZB-Mittelkurs, der über ISR eine Stunde lang gecacht wird. Das Feld meta.rateDate in jeder Währungsantwort sagt Ihnen, wann der Kurs veröffentlicht wurde (stets ein aktueller EZB-Geschäftstag). Für hochpräzise Echtzeit-Arbeit beziehen Sie die Kurse von Ihrem Broker; für alles andere ist unser Cache in Ordnung.

Was wir der API nicht hinzufügen werden

• POST-Endpunkte für zustandsbehaftete Operationen (wir haben keinen Zustand).
• Bulk-Endpunkte (iterieren Sie über die Einzelaufrufe; es ist schnell genug).
• WebSocket / Streaming (die Daten ändern sich nicht häufig genug, um das Protokoll zu rechtfertigen).
• API-Schlüssel / kostenpflichtige Stufen (siehe „Keine Authentifizierung“ oben).

Algorithmus-Details: der Anfrage-Lebenszyklus von Anfang bis Ende

Jede API-Anfrage durchläuft dieselbe sechsstufige Pipeline, sodass das beobachtbare Verhalten über alle Endpunkte einheitlich ist. Die Stufen, der Reihe nach:

1. Edge-Routing. Cloudflare gleicht die Anfrage gegen die gecachte Routen-Map ab und liefert entweder die gecachte Antwort (Währung, beliebte Einheitenpaare) oder leitet den Fehlschlag an die Next.js-Funktion weiter. p50-Latenz bei Cache-Treffer: ~25 ms; p50 bei Cache-Fehlschlag: ~70 ms.
2. Methode & CORS-Preflight. Nicht-GET-Methoden mit 405 ablehnen. Den Header Access-Control-Allow-Origin: * gemäß der WHATWG-Fetch-Spezifikation auf jede Antwort anwenden.
3. Schema-Validierung. Query-Parameter mit einem Zod-artigen Schema parsen. Fehlende oder fehlerhafte Parameter liefern 400 mit { ok: false, error: { code: "INVALID_PARAM", param } }.
4. Umrechnung auflösen. Die Ziel-Umrechnung im selben Register nachschlagen, das die Oberfläche verwendet (Einheiten, Währung, Farbe, Bild …). Bei Währung den ISR-Cache lesen; bei Einheit/Farbe ist die Funktion eine deterministische reine Berechnung.
5. Die Hülle formatieren. Stets { ok: true, data, meta }. Zahlen werden gemäß RFC 8259 als JSON-Zahlen (nicht als Strings) serialisiert, für natives Parsen beim Konsumenten.
6. Cache-Header. Währungsantworten erhalten Cache-Control: public, max-age=3600, stale-while-revalidate=86400; Einheiten-/Farbantworten erhalten max-age=31536000, immutable, weil sich die Mathematik nie ändert.

Quellen & Referenzen

Das API-Design folgt der HTTP-Semantik aus RFC 9110 und den HTTP-Caching-Regeln aus RFC 9111. Das CORS-Verhalten folgt der WHATWG-Fetch-Spezifikation. Response-Bodies verwenden UTF-8-JSON gemäß RFC 8259. Die Begründung der Fehlerhülle geht auf RFC 7807 (Problem Details) zurück. Im Quellenblock am Fuß der Seite finden Sie die maßgeblichen Spezifikationen.

Annahmen & Grenzen

• Nur GET. Kein POST/PUT/DELETE. Alles, was einen Body erfordert, bräuchte ein anderes Design und höchstwahrscheinlich eine Authentifizierung.
• Kein Parsen von Request-Bodies. Alle Eingaben sind Query-Parameter mit URL-Kodierung. Eingaben größer als ~2 KB riskieren, bei Zwischeninstanzen an URL-Längengrenzen zu stoßen.
• Rate Limits gelten am Netzwerk-Edge, nicht pro API-Schlüssel. Clients mit hohem Volumen, die sich ein NAT teilen, können sich dasselbe Kontingent teilen; spiegeln Sie die relevanten Daten für Produktionslasten lokal.
• Kein SLA. Die API ist nach bestem Bemühen. Cachen Sie aggressiv und behandeln Sie 5xx als vorübergehend.
• Kein strukturiertes WebSocket / SSE. Polling ist in Ordnung, weil sich die zugrunde liegenden Daten höchstens stündlich aktualisieren.
• Nur JSON, kein XML / msgpack. Accept-Aushandlung ist nicht implementiert.
• Zeitzonen-naive Zeitstempel in einigen Legacy-Antworten. Alle neuen Endpunkte liefern ISO 8601 mit explizitem Offset; Felder vor v1.4 sind per Konvention UTC, haben aber keinen Z-Suffix.

Live-Doku unter /api/.