Comment utiliser les APIs Cloudflare ?

En bref

Les API de Cloudflare vous permettent de gérer le DNS, les zones, les Workers, la sécurité et les analyses de manière programmatique. Authentifiez-vous avec des jetons API (recommandé) ou des clés globales, appelez `api.cloudflare.com/client/v4` et gérez les limites de débit avec élégance. Pour les tests, utilisez Apidog pour valider les modifications DNS, tester les déploiements de Workers et automatiser la configuration dans différents environnements.

Introduction

Cloudflare se trouve devant des millions de sites web. Il gère le DNS, le CDN, la protection DDoS, le WAF, les fonctions sans serveur Workers, et bien plus encore. Gérer tout cela via le tableau de bord fonctionne pour les petites configurations. Mais à grande échelle, l'automatisation est nécessaire.

L'API Cloudflare couvre tout ce que fait le tableau de bord. Vous pouvez créer des zones, mettre à jour des enregistrements DNS, configurer des règles de page, déployer des Workers, gérer les paramètres SSL et extraire des analyses. Le tout de manière programmatique.

Les développeurs utilisent l'API de Cloudflare pour :

Infrastructure en tant que code (Terraform, Pulumi)
Intégration dans les pipelines CI/CD
Gestion multi-zones
Mises à jour DNS automatisées
Déploiements de Workers

💡

Si vous développez sur Cloudflare, Apidog vous aide à tester les appels API, à valider les réponses et à documenter votre intégration. Vous pouvez enregistrer les configurations de zone en tant que requêtes réutilisables et les partager avec votre équipe.

button

Testez les API Cloudflare avec Apidog - gratuit

À la fin de ce guide, vous serez capable de :

Vous authentifier avec les jetons API Cloudflare
Gérer les zones et les enregistrements DNS
Déployer et gérer les Workers
Configurer les paramètres de sécurité
Extraire les analyses et les logs

Authentification

Cloudflare propose deux méthodes d'authentification. Utilisez les jetons API, et non les clés globales.

Méthode 1 : Jetons API (recommandé)

Les jetons API sont limités à des permissions spécifiques. Si un jeton est compromis, les dommages sont limités.

Créer un jeton :

Allez dans le Tableau de bord Cloudflare → Mon profil → Jetons API
Créer un jeton
Choisissez un modèle (Modifier le DNS de zone, Déploiement de Workers, etc.) ou personnalisé
Définir des zones spécifiques ou toutes les zones
Copiez le jeton

Utiliser le jeton :

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Méthode 2 : Clé API globale (non recommandé)

La clé globale a un accès complet au compte. Évitez de l'utiliser.

curl -X GET "https://api.cloudflare.com/client/v4/user" \
  -H "X-Auth-Email: your-email@example.com" \
  -H "X-Auth-Key: YOUR_GLOBAL_API_KEY"

Format de réponse

Toutes les réponses de l'API Cloudflare suivent cette structure :

{
  "result": { ... },
  "success": true,
  "errors": [],
  "messages": []
}

Vérifiez toujours `success` avant de traiter `result`.

Gestion des zones

Les zones représentent des domaines dans Cloudflare.

Lister les zones

curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Réponse :

{
  "result": [
    {
      "id": "023e105f4ecef8ad9ca31a8372d0c353",
      "name": "example.com",
      "status": "active",
      "paused": false,
      "type": "full",
      "development_mode": 0,
      "name_servers": [
        "ns1.cloudflare.com",
        "ns2.cloudflare.com"
      ],
      "original_name_servers": [
        "ns1.example.com"
      ],
      "original_registrar": null
    }
  ],
  "success": true
}

Créer une zone

curl -X POST "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "newdomain.com",
    "account": {
      "id": "ACCOUNT_ID"
    },
    "type": "full"
  }'

Obtenir les détails d'une zone

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Gestion des enregistrements DNS

Les enregistrements DNS associent les noms de domaine aux adresses IP et aux services.

Lister les enregistrements DNS

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Créer un enregistrement DNS

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.1",
    "ttl": 3600,
    "proxied": true
  }'

Types d'enregistrements :

`A` - Adresse IPv4
`AAAA` - Adresse IPv6
`CNAME` - Alias vers un autre domaine
`MX` - Serveur de messagerie
`TXT` - Enregistrements texte (SPF, DKIM, vérification)
`NS` - Serveur de noms

Mettre à jour un enregistrement DNS

curl -X PUT "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "content": "192.0.2.2",
    "ttl": 3600,
    "proxied": true
  }'

Supprimer un enregistrement DNS

curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/dns_records/RECORD_ID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Cloudflare Workers

Les Workers exécutent du JavaScript en périphérie, près des utilisateurs.

Lister les Workers

curl -X GET "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Uploader un Worker

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/workers/scripts/my-worker" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/javascript" \
  --data-binary @worker.js

Exemple de Worker :

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname === '/api/hello') {
      return new Response(JSON.stringify({ message: 'Hello from the edge!' }), {
        headers: { 'Content-Type': 'application/json' }
      })
    }
    
    return fetch(request)
  }
}

Lier une route

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/workers/routes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pattern": "example.com/api/*",
    "script": "my-worker"
  }'

Espace de noms KV Worker

Stocker des données accessibles depuis les Workers :

curl -X POST "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/storage/kv/namespaces" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "my-kv-namespace"
  }'

Sécurité et WAF

Règles de page

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/pagerules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targets": [
      {
        "target": "url",
        "constraint": {
          "operator": "matches",
          "value": "example.com/*"
        }
      }
    ],
    "actions": [
      {
        "id": "ssl",
        "value": "flexible"
      },
      {
        "id": "cache_level",
        "value": "aggressive"
      }
    ]
  }'

Règles de pare-feu

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/firewall/rules" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "expression": "ip.geoip.country eq \"CN\"",
      "paused": false
    },
    "action": "block",
    "description": "Bloquer le trafic venant de Chine"
  }'

Limitation de débit

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/rate_limits" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "disabled": false,
    "description": "Limiter le débit des points d'accès API",
    "match": {
      "request": {
        "methods": ["POST"],
        "url_pattern": "*/api/*"
      }
    },
    "threshold": 100,
    "period": 60,
    "action": {
      "mode": "ban",
      "timeout": 600
    }
  }'

Analyses et logs

Analyses de zone

curl -X GET "https://api.cloudflare.com/client/v4/zones/ZONE_ID/analytics/dashboard?since=-1440&continuous=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Réponse :

{
  "result": {
    "totals": {
      "requests": {
        "all": 1000000,
        "cached": 800000,
        "uncached": 200000
      },
      "bandwidth": {
        "all": 50000000000,
        "cached": 40000000000
      },
      "threats": {
        "all": 5000
      },
      "pageviews": {
        "all": 250000
      }
    }
  }
}

Logs de zone (Logpush)

Activez Logpush pour envoyer les logs à votre stockage :

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/logpush/jobs" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mon travail Logpush",
    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
    "dataset": "http_requests",
    "logpull_options": "fields=ClientIP,ClientRequestPath,EdgeResponseStatus&timestamps=rfc3339"
  }'

Tester avec Apidog

Les modifications Cloudflare affectent le trafic de production. Testez en profondeur.

1. Configuration de l'environnement

CLOUDFLARE_API_TOKEN: your_token
CLOUDFLARE_ACCOUNT_ID: abc123
ZONE_ID: xyz789
BASE_URL: https://api.cloudflare.com/client/v4

2. Valider les réponses

pm.test('La requête a réussi', () => {
  const response = pm.response.json()
  pm.expect(response.success).to.be.true
  pm.expect(response.errors).to.be.empty
})

pm.test('Enregistrement DNS créé correctement', () => {
  const response = pm.response.json()
  pm.expect(response.result.type).to.eql('A')
  pm.expect(response.result.name).to.eql('www')
  pm.expect(response.result.proxied).to.be.true
})

3. Tester les déploiements de Workers

Enregistrez les scripts Worker comme fichiers dans Apidog et testez les téléchargements :

pm.test('Worker téléchargé', () => {
  const response = pm.response.json()
  pm.expect(response.result.id).to.eql('my-worker')
})

Testez les API Cloudflare avec Apidog - gratuit

Erreurs courantes et solutions

403 Interdit

Cause : Le jeton ne dispose pas de la permission requise.

Solution : Vérifiez les permissions du jeton dans le tableau de bord Cloudflare. Les modifications DNS nécessitent Zone:DNS:Edit. Les Workers nécessitent Account:Workers:Edit.

1003 : Zone invalide ou manquante

Cause : L'ID de zone n'existe pas ou le jeton ne peut pas y accéder.

Solution : Vérifiez l'ID de zone dans l'URL et assurez-vous que la portée du jeton inclut cette zone.

81057 : L'enregistrement existe déjà

Cause : Un enregistrement DNS avec le même nom et le même type existe déjà.

Solution : Utilisez PUT pour mettre à jour au lieu de POST pour créer, ou supprimez d'abord.

Limite de débit dépassée

Cause : Trop de requêtes (par défaut 1200/5 minutes).

Solution : Implémentez un mécanisme de recul (backoff) et des opérations par lots.

async function updateRecords(records) {
  for (const record of records) {
    try {
      await updateRecord(record)
      await sleep(100) // Tampon de limitation de débit
    } catch (error) {
      if (error.status === 429) {
        await sleep(60000) // Attendre une minute
        await updateRecord(record) // Réessayer
      }
    }
  }
}

Alternatives et comparaisons

Fonctionnalité	Cloudflare	AWS Route 53	Fastly
API DNS	✓	✓	✓
API CDN	✓	API CloudFront	✓
Fonctions Edge	Workers	Lambda@Edge	Compute@Edge
API WAF	✓	AWS WAF	✓
Niveau gratuit	Généreux	Paiement à l'utilisation	Limité
Format de réponse	JSON	XML/JSON	JSON

L'API de Cloudflare est plus unifiée que les services fragmentés d'AWS. Les Workers offrent plus de flexibilité que Lambda@Edge.

Cas d'utilisation concrets

SaaS multi-tenant. Une plateforme crée automatiquement des zones Cloudflare lorsque les clients ajoutent des domaines personnalisés. Les Workers gèrent le routage, les enregistrements DNS sont créés via l'API, et les certificats SSL sont provisionnés automatiquement.

Déploiements bleu-vert. Une équipe d'ingénieurs utilise les mises à jour d'enregistrements DNS pour basculer le trafic entre les environnements. L'API met à jour les enregistrements A pendant le déploiement, avec une propagation instantanée via le réseau de Cloudflare.

Automatisation de la réponse DDoS. Une équipe de sécurité surveille le trafic via l'API d'analyse. Lorsque des schémas d'attaque apparaissent, des règles de pare-feu sont ajoutées via l'API pour bloquer les IP malveillantes, réduisant le temps de réponse de plusieurs heures à quelques secondes.

En résumé

Voici ce que vous avez appris :

Vous authentifier avec des jetons API pour un accès limité
Gérer les zones et les enregistrements DNS de manière programmatique
Déployer des Workers pour le calcul en périphérie
Configurer la sécurité avec des règles de pare-feu et la limitation de débit
Extraire les analyses et configurer l'acheminement des logs
Tester avec Apidog avant d'appliquer en production

button

FAQ

Quelle est la différence entre une zone et un domaine ?Une zone est la représentation d'un domaine par Cloudflare. Lorsque vous ajoutez un domaine à Cloudflare, vous créez une zone. L'ID de zone est utilisé dans les appels API pour ce domaine.

Comment trouver mon ID de zone ?Allez dans le Tableau de bord Cloudflare → sélectionnez votre domaine → Aperçu → faites défiler jusqu'à la section API. L'ID de zone y est affiché.

Puis-je utiliser l'API Cloudflare sans forfait payant ?Oui. La plupart des fonctionnalités de l'API fonctionnent avec les forfaits gratuits. Les Workers disposent d'un niveau gratuit généreux. Certaines fonctionnalités avancées (règles WAF avancées, Logpush) nécessitent des forfaits payants.

Combien de temps les modifications DNS prennent-elles ?Les modifications via l'API sont immédiates dans le système de Cloudflare. La propagation aux serveurs de noms Cloudflare prend quelques secondes. La propagation globale dépend du TTL et des résolveurs récursifs, généralement quelques minutes.

Quelle est la limite de débit ?Par défaut : 1200 requêtes toutes les 5 minutes par jeton. Vérifiez l'en-tête `X-RateLimit-Remaining`. Les forfaits Enterprise ont des limites plus élevées.

Puis-je gérer plusieurs comptes avec un seul jeton ?Non. Les jetons sont limités à un seul compte. Pour plusieurs comptes, créez des jetons distincts ou utilisez des jetons de niveau utilisateur avec accès à plusieurs comptes.

En quoi les Workers diffèrent-ils de Lambda ?Les Workers s'exécutent dans les emplacements périphériques de Cloudflare (plus de 300 villes), et non dans des régions spécifiques. Les démarrages à froid sont minimes. Ils sont idéaux pour la manipulation de requêtes/réponses, et non pour les processus de longue durée.

Puis-je utiliser l'API pour purger le cache ?Oui :

curl -X POST "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://example.com/style.css"]
  }'