Links von Hand anzulegen ist völlig in Ordnung – bis es das nicht mehr ist. Sobald jede Bestellung einen Tracking-Link braucht, jeder Nutzer einen Empfehlungslink oder jedes Inserat einen QR-Code, brauchen Sie dasselbe programmatisch. Genau dafür gibt es eine URL-Shortener-API – und die Oberfläche ist klein genug, dass Sie das bei einem Kaffee verdrahten.

Was sich automatisieren lässt

  • Links pro Bestellung oder pro Nutzer, erzeugt genau in dem Moment, in dem sie gebraucht werden.
  • Kampagnenlinks in Serie – einer pro Kanal, in einer Schleife aus der Tabelle erzeugt statt per Hand.
  • QR-Codes on the fly für Tickets, Rechnungen, Etiketten und Lieferscheine.
  • Klickdaten zurückgeholt ins eigene Dashboard, damit die Zahlen dort stehen, wo Ihr Team ohnehin hinsieht.

Falls Sie unsicher sind, ob Sie die API überhaupt brauchen: Der ehrliche Test heißt Menge und Wiederholung. Wenn Sie dasselbe mehr als ein paar Mal pro Woche im Browser tun, automatisieren Sie es.

Authentifizieren

Ihren Schlüssel holen Sie sich auf der Kontoseite und schicken ihn bei jedem Request als X-Api-Key-Header mit. Zwei Regeln sind nicht verhandelbar: Der Schlüssel bleibt serverseitig – alles in Frontend-JavaScript ist öffentlich, und ein geleakter Schlüssel lässt Fremde in Ihrem Namen Links anlegen – und rotieren Sie ihn sofort, wenn er je in einem Repository oder einem Log landet.

Einen Link anlegen

Ein POST auf /api/getLink.json mit dem Ziel. Alias, Modus, Ablauf und Passwort können Sie im selben Aufruf mitgeben:

curl -X POST https://urlik.xyz/api/getLink.json -H "X-Api-Key: YOUR_KEY" -d "url=https://example.com/very/long/path" -d "alias=spring-sale"

Die Antwort ist JSON und enthält die Kurz-URL, ihre QR-URL und ihre Statistik-URL. Mit einem Schlüssel erzeugte Links hängen an Ihrem Konto, tauchen also im Dashboard auf und lassen sich später bearbeiten.

Ein Detail, das Sie vor dem Bauen kennen sollten: Ein Alias ist dienstweit eindeutig. Ist spring-sale vergeben, bekommen Sie einen Fehler und keinen stillen Ersatz – fangen Sie diesen Fall also ab oder versehen Sie Ihre Aliase mit einem Namensraum (acme-spring-sale).

Einen QR-Code erzeugen

GET /api/qr.json nimmt die Daten plus optional format, fg, bg, ecc und size und liefert den QR-Code zurück. Richten Sie ihn auf einen Kurzlink statt auf eine rohe lange URL – Sie bekommen einen saubereren, robusteren Code, und das Ziel bleibt anschließend änderbar. Das ist das Muster dynamischer QR-Code, erledigt aus Ihrem Backend.

Die Statistik auslesen

GET /api/stats.json liefert Summen, eine Zeitreihe, Referrer, Geräte und Länder zu einem Link – dieselben Zahlen wie die Statistikseite, nur in einer Form, die Sie in Ihr eigenes Admin-Panel stellen können.

Fragen Sie sie nach Zeitplan ab, nicht bei jedem Seitenaufruf. Klickstatistiken sind kein Echtzeit-System of Record, und den Endpunkt zu bombardieren, um ein Diagramm neu zu zeichnen, das niemand ansieht, ist der direkte Weg zum Rate Limit.

So bauen, dass es um 3 Uhr nachts hält

Die Endpunkte sind simpel; scheitern tun die Integrationen, die annehmen, es gehe nie etwas schief. Vier Gewohnheiten, die sich bezahlt machen:

  • Prüfen Sie die Antwort. Immer. Jeder Aufruf liefert einen Status – lesen Sie ihn. Der Klassiker: Erfolg annehmen, einen Fehler-Body speichern, als wäre er ein Kurzlink, und ihn dann auf einer gedruckten Rechnung wiederfinden.
  • Blockieren Sie nie den Nutzer wegen eines Links. Wenn im Checkout gekürzt wird, wird aus einer langsamen API ein langsamer Checkout. Erledigen Sie das in einem Hintergrund-Job oder weichen Sie auf die lange URL aus und versuchen es später erneut. Die lange URL funktioniert immer, das ist Ihr Sicherheitsnetz.
  • Cachen Sie, was sich nicht ändert. Dasselbe Ziel muss nicht zweimal gekürzt werden – speichern Sie die Kurz-URL am Quelldatensatz und verwenden Sie sie wieder. Billiger, schneller, und Ihr Dashboard bleibt lesbar.
  • Bremsen Sie bei Fehlern ab. Wiederholen Sie mit wachsenden Abständen statt in einer engen Schleife. Ein Rate Limit, das man mit einem Retry-Sturm beantwortet, bleibt ein Rate Limit.

Wo die API aufhört

Zwei ehrliche Grenzen. Rate Limits gibt es, und großzügig heißt nicht unendlich – Batch-Jobs gehören dosiert, nicht auf einen Schlag abgefeuert. Und die API legt Links an; sie entscheidet nicht, was drinstehen soll. Versehen Sie Ihre Links schon beim Anlegen mit UTM-Parametern (siehe UTM-Guide), sonst automatisieren Sie die Produktion von Tausenden Links, die Sie in der Analytics nicht auseinanderhalten können – und das ist schlimmer als Handarbeit.

Kurz gefasst

Ein Endpunkt zum Anlegen, einer für QR, einer für die Statistik, ein Header für die Auth. Schlüssel serverseitig halten, jede Antwort prüfen, die Arbeit vom kritischen Pfad nehmen, Wiederkehrendes cachen und schon beim Anlegen taggen. Die vollständige Parameterliste, die Fehlercodes und Beispiele stehen in der API-Dokumentation; wenn Sie zuerst den konzeptionellen Unterbau wollen, beginnen Sie bei was ein URL-Shortener ist.