QR-Code Bild-API

Alles nach /qr/ ist die Nutzlast, einschließlich ihrer eigenen Query-Parameter. Der Server dekodiert den Pfad, kodiert ihn als QR-Code und liefert ein Bild zurück. Ohne weitere Angaben ist das ein PNG mit 512 Pixeln Kantenlänge, Fehlerkorrektur M, 2 Modulen Ruhezone, Schwarz auf Weiß. Es gibt weder einen Kurz-URL-Dienst noch eine Weiterleitung: Der Code enthält Ihre Adresse wörtlich und funktioniert deshalb weiter, auch wenn es diese Seite einmal nicht mehr gibt.

Die Optionen sind Query-Parameter: ?size=1024, ?dark=7c3aed&light=transparent, ?format=svg. Gespeichert wird nichts, und geglaubt wird auch nichts – jeder Wert wird gegen einen festen Bereich geprüft. Ein falscher Wert führt zu 400 mit einer Meldung, die den Parameter nennt, statt stillschweigend ignoriert zu werden.

Antworten tragen Cache-Control: public, max-age=86400 und einen offenen CORS-Header; ein wiederholt angefragter Link kommt also aus dem Cache, und das Bild lässt sich aus eigenem JavaScript laden. Weil der Cache-Schlüssel die vollständige URL ist, sind zwei verschiedene Optionssätze zwei verschiedene Bilder.

Die Nutzlast steht im Pfad, deshalb funktioniert eine Adresse mit eigenem ? und & ohne Maskierung: /qr/https://shop.example/p?id=42&ref=plakat kodiert genau diese Adresse. Nur die acht Namen aus der Tabelle oben gelten als Optionen, exakt und mit Beachtung der Groß- und Kleinschreibung; jeder andere Parameter bleibt Teil dessen, was kodiert wird.

Eine Kollision bleibt, und die verschweigen wir nicht: eine Zieladresse, die selbst size, margin, ec, dark, light, format, download oder data enthält. Bei /qr/https://shop.example/p?size=XL lässt sich Ihr Parameter nicht von unserem unterscheiden; size=XL wird als Option gelesen und endet in einer 400. Es gibt zwei eindeutige Auswege:

Der Endpunkt ist kostenlos und ohne Authentifizierung – das funktioniert nur, wenn alle vernünftig damit umgehen. Er ist dafür gedacht, Codes in Dokumente, Dashboards und E-Mails einzubetten, nicht dafür, hunderttausende Bilder in einem Rutsch zu rendern. Wer dieses Volumen braucht, lässt dieselbe Bibliothek, node-qrcode, problemlos auf dem eigenen Rechner laufen.

Ein PNG ist bei 1024 Pixeln gedeckelt, weil Rendern nicht umsonst ist und niemand sich dafür anmelden muss: ein Rasterbild wird Pixel für Pixel auf einem Server mit einem einzigen Thread gezeichnet, die Kosten wachsen also mit der Fläche, und einige wenige große Anfragen gleichzeitig würden die ganze Seite ausbremsen. Ein SVG hat diese Kosten nicht – die Größe landet nur in den Attributen width und height –, deshalb reicht format=svg bis 2048 Pixel und skaliert auch darüber hinaus verlustfrei, was für den Druck ohnehin die richtige Wahl ist. Wer ein größeres PNG anfordert, bekommt eine 400, die genau das sagt und format=svg nennt. Das Einzige, was die API bewusst nicht kann, ist das Logo in der Mitte: dafür braucht es Ihre Bilddatei, deshalb bleibt das im QR-Code Generator, wo die Montage in Ihrem Browser passiert. Kombinieren Sie es mit ec=h, damit der Code die verdeckten Module verkraftet.