Entwickler & API 9 Min. Lesezeit von Knapp. Team

URL Shortener API für Entwickler: Integration, Endpoints & Code-Beispiele

URL Shortener API in deine App integrieren: REST-Endpoints, Authentifizierung, Rate-Limits und Code-Beispiele für PHP, JavaScript und Python. DSGVO-konform, EU-gehostet.

URL-Kürzung ist eine der einfachsten Aufgaben in der Webentwicklung – solange du sie manuell machst. Sobald du Links programmatisch erstellen, verwalten oder tracken musst, brauchst du eine API.

Ob du Links in automatisierten E-Mail-Kampagnen kürzst, QR-Codes für individualisierte Angebote generierst oder Analytics-Daten in dein eigenes Dashboard importierst: Eine sauber dokumentierte REST-API macht den Unterschied zwischen einem tagelagen Integrationsprojekt und einem 30-Minuten-Job.

Dieser Artikel zeigt, was eine gute URL-Shortener-API leisten muss, wie du die Knapp.-API integrierst und gibt dir fertige Code-Beispiele für die gängigsten Stacks.

Was macht eine gute URL-Shortener-API aus?

REST-Konformität

Eine gute API folgt REST-Prinzipien: HTTP-Verben (GET, POST, PATCH, DELETE) für die richtigen Aktionen, klare Ressourcen-Struktur, JSON als primäres Datenformat, aussagekräftige HTTP-Status-Codes.

Authentifizierung

API-Key-basierte Authentifizierung ist Standard. Bearer-Token (Authorization-Header) ist sicherer als Query-Parameter, weil Keys nicht in Server-Logs auftauchen.

Rate-Limiting mit klaren Headern

Jede API-Antwort sollte Informationen über verbleibende Limits enthalten:

  • X-RateLimit-Limit: Maximale Requests pro Zeitfenster
  • X-RateLimit-Remaining: Verbleibende Requests
  • X-RateLimit-Reset: Zeitstempel des nächsten Reset

DSGVO-Konformität

Besonders relevant für EU-Entwickler: Die API darf keine personenbezogenen Daten (IP-Adressen, User-Agents) unverarbeitet an US-Server übermitteln. EU-Hosting und transparente Datenverarbeitung sind Pflicht.

Webhook-Support

Für Event-getriebene Architekturen: Webhooks bei Link-Erstellung, Klick-Ereignissen oder Analytics-Schwellenwerten.

Knapp. API: Überblick

Base URL

https://api.knapp.at/v1

Authentifizierung

Authorization: Bearer <your_api_key>
Content-Type: application/json

API-Keys erstellst du im Dashboard unter Einstellungen → API → Neuer API-Key. Vergib aussagekräftige Namen pro Integration (z. B. newsletter-system, crm-integration).

Verfügbarkeit

Die API ist im Pro-Plan (9€/Monat) und Agentur-Plan (39€/Monat) verfügbar.

Endpoints im Überblick

Links

| Method | Endpoint | Beschreibung | |--------|----------|--------------| | POST | /links | Neuen Kurzlink erstellen | | GET | /links | Alle Links auflisten | | GET | /links/{id} | Einzelnen Link abrufen | | PATCH | /links/{id} | Link aktualisieren | | DELETE | /links/{id} | Link löschen |

Analytics

| Method | Endpoint | Beschreibung | |--------|----------|--------------| | GET | /links/{id}/stats | Klick-Statistiken für einen Link | | GET | /links/{id}/stats/timeline | Klicks nach Zeitverlauf | | GET | /links/{id}/stats/countries | Klicks nach Land | | GET | /links/{id}/stats/devices | Klicks nach Gerätetyp |

QR-Codes

| Method | Endpoint | Beschreibung | |--------|----------|--------------| | POST | /links/{id}/qr | QR-Code für Link generieren | | GET | /links/{id}/qr | QR-Code herunterladen |

Code-Beispiele

Link erstellen (JavaScript / Node.js)

const response = await fetch('https://api.knapp.at/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    destination: 'https://meinewebsite.at/produkt/sommer-kollektion',
    slug: 'sommer26',          // optional, auto-generiert wenn leer
    domain: 'links.meinewebsite.at',  // optional, Standarddomain wenn leer
    tags: ['kampagne-sommer', 'print'],  // optional
    expires_at: '2026-09-30T23:59:59Z'  // optional
  })
});

const link = await response.json();
console.log(link.short_url);  // https://links.meinewebsite.at/sommer26

Antwort:

{
  "id": "lnk_abc123xyz",
  "short_url": "https://links.meinewebsite.at/sommer26",
  "destination": "https://meinewebsite.at/produkt/sommer-kollektion",
  "slug": "sommer26",
  "domain": "links.meinewebsite.at",
  "created_at": "2026-05-10T09:15:00Z",
  "expires_at": "2026-09-30T23:59:59Z",
  "tags": ["kampagne-sommer", "print"],
  "clicks": 0
}

Link erstellen (PHP)

<?php
$apiKey = 'YOUR_API_KEY';
$payload = [
    'destination' => 'https://meinewebsite.at/produkt/sommer-kollektion',
    'slug' => 'sommer26',
    'tags' => ['kampagne-sommer', 'print']
];

$ch = curl_init('https://api.knapp.at/v1/links');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
$link = json_decode($response, true);
echo $link['short_url'];

Link erstellen (Python)

import requests

api_key = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "destination": "https://meinewebsite.at/produkt/sommer-kollektion",
    "slug": "sommer26",
    "tags": ["kampagne-sommer", "print"]
}

response = requests.post(
    "https://api.knapp.at/v1/links",
    json=payload,
    headers=headers
)

link = response.json()
print(link["short_url"])

Analytics abrufen (JavaScript)

// Klick-Statistiken für letzten 30 Tage
const statsResponse = await fetch(
  'https://api.knapp.at/v1/links/lnk_abc123xyz/stats?period=30d',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const stats = await statsResponse.json();
console.log(`Gesamt-Klicks: ${stats.total_clicks}`);
console.log(`Unique Klicks: ${stats.unique_clicks}`);

Antwort:

{
  "link_id": "lnk_abc123xyz",
  "period": "30d",
  "total_clicks": 1247,
  "unique_clicks": 983,
  "top_country": "AT",
  "top_device": "mobile",
  "breakdown": {
    "countries": [
      {"code": "AT", "clicks": 612},
      {"code": "DE", "clicks": 389},
      {"code": "CH", "clicks": 144}
    ],
    "devices": [
      {"type": "mobile", "clicks": 892},
      {"type": "desktop", "clicks": 312},
      {"type": "tablet", "clicks": 43}
    ]
  }
}

QR-Code generieren und herunterladen (JavaScript)

// QR-Code für Link generieren
const qrResponse = await fetch(
  'https://api.knapp.at/v1/links/lnk_abc123xyz/qr',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      format: 'svg',              // 'svg' oder 'png'
      size: 300,                  // Pixel (bei PNG)
      error_correction: 'M',     // L, M, Q, H
      foreground_color: '#000000',
      background_color: '#FFFFFF'
    })
  }
);

// SVG direkt als String
const svgContent = await qrResponse.text();

Massenerstellung: Bulk-Endpoint

Für Anwendungsfälle mit vielen Links (E-Mail-Kampagnen, individualisierte QR-Codes für Produktverpackungen):

const bulkResponse = await fetch('https://api.knapp.at/v1/links/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    links: [
      { destination: 'https://meinewebsite.at/produkt/1', slug: 'prod-1' },
      { destination: 'https://meinewebsite.at/produkt/2', slug: 'prod-2' },
      { destination: 'https://meinewebsite.at/produkt/3', slug: 'prod-3' }
    ]
  })
});

Bulk-Erstellung bis zu 100 Links pro Request. Für größere Batches: Pagination oder Async-Job via Webhook.

Webhooks

Webhooks ermöglichen Event-getriebene Integrationen:

// Webhook-Endpoint in deiner App
app.post('/webhook/knapp', (req, res) => {
  const event = req.body;
  
  if (event.type === 'link.clicked') {
    const { link_id, country, device, timestamp } = event.data;
    // In eigene Datenbank schreiben, CRM aktualisieren, etc.
  }
  
  res.status(200).send('OK');
});

Konfiguriere Webhook-URLs im Dashboard unter Einstellungen → Webhooks.

Fehlerbehandlung

const response = await fetch('https://api.knapp.at/v1/links', { /* ... */ });

if (!response.ok) {
  const error = await response.json();
  
  switch (response.status) {
    case 400:
      console.error('Ungültige Anfrage:', error.message);
      break;
    case 401:
      console.error('API-Key ungültig oder abgelaufen');
      break;
    case 409:
      console.error('Slug bereits vergeben:', error.message);
      break;
    case 429:
      const resetTime = response.headers.get('X-RateLimit-Reset');
      console.error(`Rate-Limit erreicht. Reset um: ${resetTime}`);
      break;
    default:
      console.error('API-Fehler:', error.message);
  }
}

DSGVO-Hinweise für Entwickler

Wenn du die Knapp.-API verwendest, bist du datenschutzrechtlich Auftragsverarbeiter (wenn du Links für Dritte erstellst) oder Verantwortlicher (wenn du Links für eigene Kampagnen erstellst).

Relevante Punkte:

  • Knapp. verarbeitet Klickdaten auf EU-Servern
  • IP-Adressen werden vor Speicherung anonymisiert
  • Kein Datentransfer in Drittländer
  • AVV im Pro-Plan enthalten und erforderlich für B2B-Verarbeitung

Wenn du Knapp. in einem Produkt einsetzt, das du an Kunden lieferst, benötigst du möglicherweise einen Sub-AVV mit Knapp. – kontaktiere uns für Enterprise-Verträge.

Fazit

Eine saubere URL-Shortener-API macht Automatisierungen, die ohne API tagelange Handarbeit wären, zur 30-Minuten-Aufgabe. Wichtig für EU-Entwickler: Die API muss EU-gehostet und DSGVO-konform sein – sonst übernimmst du das Datenschutzrisiko für alle deine Kunden.

Die Knapp.-API ist ab dem Pro-Plan verfügbar und deckt alle gängigen Anwendungsfälle ab: Link-Erstellung, Analytics-Abruf, QR-Code-Generierung und Bulk-Operationen.

Jetzt kostenlos mit Knapp. starten – API-Zugang im Pro-Plan (9€/Monat), EU-Hosting, vollständige Dokumentation und DSGVO-konformes Tracking.