API URLW en JavaScript : intégration Node.js complète avec fetch

Que vous construisiez un backend Node.js, un worker Cloudflare ou un script d'automatisation, intégrer l'API URLW en JavaScript est rapide et sans dépendances externes. Voici un guide complet avec du code prêt à déployer.

Configuration et authentification

L'API URLW s'authentifie via un Bearer token dans les en-têtes HTTP. En Node.js, stockez votre clé API dans une variable d'environnement :

# Dans votre fichier .env (jamais versionné !)
URLW_API_KEY=votre_cle_api_ici

// 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('La variable d\'environnement URLW_API_KEY est requise');
}

module.exports = { URLW_API_BASE, URLW_API_KEY };

Raccourcir une URL avec fetch en Node.js

Voici une classe UrlwClient complète utilisant l'API fetch native (disponible en 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(
    `Erreur API URLW (${response.status}) : ${error.message || 'Erreur inconnue'}`
  );
}

return response.json();
}

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

if (!response.ok) {
  throw new Error(`Impossible de récupérer les stats : 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(`Erreur lors de la récupération des liens : HTTP ${response.status}`);
}

return response.json();
}
}

module.exports = UrlwClient;

Exemple d'utilisation pratique

Voici comment utiliser ce client dans un script Node.js :

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

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

try {
// Créer un lien court avec un slug personnalisé
const link = await client.shorten(
  'https://exemple.com/article-tres-long-avec-parametres?utm_source=newsletter',
  {
    slug: 'article-juin',
    domain: 'go.votre-marque.fr',
  }
);

console.log('Lien court :', link.short_url);
console.log('ID du lien :', link.id);

// Récupérer les stats 24h plus tard
const stats = await client.getStats(link.id);
console.log(`Clics : ${stats.total_clicks} (${stats.unique_clicks} uniques)`);

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

main();

Gestion des erreurs et retry automatique

Pour une application en production, implémentez un mécanisme de retry avec backoff exponentiel pour gérer les erreurs transitoires et les limites de taux :

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

  // Attendre avant de réessayer : 1s, 2s, 4s...
  const delayMs = Math.pow(2, attempt - 1) * 1000;
  console.warn(`Tentative ${attempt} échouée, nouvel essai dans ${delayMs}ms`);
  await new Promise(resolve => setTimeout(resolve, delayMs));
}
}
}

// Utilisation
const link = await withRetry(() => client.shorten('https://exemple.com/page'));

Pour un usage TypeScript, les interfaces et types de l'API URLW sont disponibles dans la documentation officielle. Pour commencer, créez votre compte URLW et générez votre clé API.