URLW-API in JavaScript: vollständige Node.js-Integration mit fetch

Ob Sie ein Node.js-Backend, einen Cloudflare-Worker oder ein Automatisierungsskript erstellen – die Integration der URLW-API in JavaScript ist schnell und ohne externe Abhängigkeiten möglich. Hier ist ein vollständiger Leitfaden mit deploy-bereitem Code.

Konfiguration und Authentifizierung

Die URLW-API authentifiziert sich über ein Bearer-Token in den HTTP-Headern. Speichern Sie in Node.js Ihren API-Schlüssel in einer Umgebungsvariable:

# In Ihrer .env-Datei (niemals versioniert!)
URLW_API_KEY=ihr_api_schluessel_hier

// config.js
const URLW_API_BASE = 'https://urlw.fr/api/v1';
const URLW_API_KEY = process.env.URLW_API_KEY;

if (!URLW_API_KEY) {
throw new Error('Die Umgebungsvariable URLW_API_KEY ist erforderlich');
}

module.exports = { URLW_API_BASE, URLW_API_KEY };

Eine URL mit fetch in Node.js kürzen

Hier ist eine vollständige UrlwClient-Klasse, die die native fetch-API verwendet (verfügbar in Node.js 18+):

// urlw-client.js
const { URLW_API_BASE, URLW_API_KEY } = require('./config');

class UrlwClient {
constructor(apiKey = URLW_API_KEY) {
this.apiKey = apiKey;
this.baseUrl = URLW_API_BASE;
}

get headers() {
return {
  'Authorization': `Bearer ${this.apiKey}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json',
};
}

async shorten(url, options = {}) {
const body = { url, ...options };

const response = await fetch(`${this.baseUrl}/links`, {
  method: 'POST',
  headers: this.headers,
  body: JSON.stringify(body),
});

if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(
    `URLW-API-Fehler (${response.status}): ${error.message || 'Unbekannter Fehler'}`
  );
}

return response.json();
}

async getStats(linkId) {
const response = await fetch(`${this.baseUrl}/links/${linkId}/stats`, {
  headers: this.headers,
});

if (!response.ok) {
  throw new Error(`Statistiken konnten nicht abgerufen werden: HTTP ${response.status}`);
}

return response.json();
}

async list(page = 1, limit = 50) {
const params = new URLSearchParams({ page, limit });
const response = await fetch(`${this.baseUrl}/links?${params}`, {
  headers: this.headers,
});

if (!response.ok) {
  throw new Error(`Fehler beim Abrufen der Links: HTTP ${response.status}`);
}

return response.json();
}
}

module.exports = UrlwClient;

Praktisches Verwendungsbeispiel

So verwenden Sie diesen Client in einem Node.js-Skript:

// main.js
const UrlwClient = require('./urlw-client');

async function main() {
const client = new UrlwClient();

try {
// Kurzlink mit benutzerdefiniertem Slug erstellen
const link = await client.shorten(
  'https://beispiel.de/artikel-mit-langen-parametern?utm_source=newsletter',
  {
    slug: 'artikel-juni',
    domain: 'go.ihre-marke.de',
  }
);

console.log('Kurzlink:', link.short_url);
console.log('Link-ID:', link.id);

// Statistiken abrufen
const stats = await client.getStats(link.id);
console.log(`Klicks: ${stats.total_clicks} (${stats.unique_clicks} eindeutig)`);

} catch (error) {
console.error('Fehler:', error.message);
process.exit(1);
}
}

main();

Fehlerbehandlung und automatischer Retry

Für eine Produktionsanwendung implementieren Sie einen Retry-Mechanismus mit exponentiellem Backoff, um transiente Fehler und Rate Limits zu behandeln:

async function withRetry(fn, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
  return await fn();
} catch (error) {
  if (attempt === maxRetries) throw error;

  // Vor dem erneuten Versuch warten: 1s, 2s, 4s...
  const delayMs = Math.pow(2, attempt - 1) * 1000;
  console.warn(`Versuch ${attempt} fehlgeschlagen, neuer Versuch in ${delayMs}ms`);
  await new Promise(resolve => setTimeout(resolve, delayMs));
}
}
}

// Verwendung
const link = await withRetry(() => client.shorten('https://beispiel.de/seite'));

Für die Verwendung mit TypeScript sind die Interfaces und Typen der URLW-API in der offiziellen Dokumentation verfügbar. Um zu starten, erstellen Sie Ihr URLW-Konto und generieren Sie Ihren API-Schlüssel.