Le API di Cloudflare

Le API di Cloudflare offrono un accesso programmatico a quasi tutte le funzionalità della piattaforma: gestione dei DNS, configurazione dei firewall, impostazioni di sicurezza, regole di caching, gestione dei worker e molto altro. Comprendere come sono strutturate e come autenticarvisi è essenziale per automatizzare la gestione delle proprietà web su larga scala.

Panoramica dell'architettura delle API

Cloudflare espone principalmente API RESTful basate su HTTPS, con endpoint organizzati per risorsa. Gli URL seguono in genere lo schema: 


https://api.cloudflare.com/client/v4/risorsa/...

Le risorse principali ruotano attorno al concetto di account e zone:

  • Account: rappresenta l'entità organizzativa (azienda, progetto, cliente).
  • Zone: corrispondono in genere a un dominio (ad esempio esempio.com) e racchiudono impostazioni DNS, sicurezza e performance.

Molti endpoint richiedono di specificare l'identificativo dell'account o della zona, valore che si può recuperare dalla dashboard oppure tramite apposite chiamate API.

Autenticazione e sicurezza

Cloudflare supporta diversi metodi di autenticazione, ma quelli più utilizzati in automazione sono:

  • API Token: raccomandato; consente di limitare i permessi a specifiche risorse e azioni.
  • API Key globale: meno granulare, fornisce accesso ampio all'account e andrebbe usata con cautela.

Autenticazione tramite API Token

Una volta creato un API Token dalla dashboard Cloudflare, lo si utilizza nelle richieste HTTP tramite un header Authorization in stile Bearer token. Esempio con curl: 


curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"

Questa chiamata permette di verificare la validità del token e i permessi associati.

Autenticazione tramite API Key globale

Con la Global API Key si utilizzano gli header X-Auth-Email e X-Auth-Key: 


curl -X GET "https://api.cloudflare.com/client/v4/user"   -H "X-Auth-Email: user@example.com"   -H "X-Auth-Key: <GLOBAL_API_KEY>"   -H "Content-Type: application/json"

È consigliato preferire gli API Token, più sicuri e facilmente revocabili o sostituibili.

Struttura delle richieste e delle risposte

Le API di Cloudflare accettano e restituiscono dati in formato JSON. Le richieste includono in genere:

  • Il metodo HTTP corretto (GET, POST, PUT, PATCH, DELETE).
  • Gli header di autenticazione.
  • Talvolta parametri di query per filtrare risultati o controllare la paginazione.
  • Un corpo JSON per operazioni di creazione o aggiornamento.

Le risposte seguono una struttura coerente, che include campi come:

  • success: booleano che indica l'esito della richiesta.
  • errors e messages: eventuali errori o messaggi informativi.
  • result: l'oggetto o la lista di oggetti richiesti.

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

Gestione delle zone e dei record DNS

Elencare le zone

Per ottenere la lista delle zone associate al tuo account: 


curl -X GET "https://api.cloudflare.com/client/v4/zones"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"

La risposta includerà tra l'altro l'identificatore di ogni zona, necessario per operazioni successive.

Elencare i record DNS di una zona

Una volta nota la zone_id, si possono elencare i record DNS: 


curl -X GET "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"

È possibile filtrare per tipo di record, nome o contenuto aggiungendo parametri di query, ad esempio: 


curl -X GET "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records?type=A&name=www.esempio.com"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"

Creare un record DNS

Per creare un nuovo record DNS A: 


curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"   --data '{
    "type": "A",
    "name": "www",
    "content": "203.0.113.10",
    "ttl": 120,
    "proxied": true
  }'

Il campo proxied controlla se il traffico passa attraverso la rete di Cloudflare (icona arancione) oppure se punta direttamente all'origin (icona grigia).

Aggiornare o eliminare un record DNS

Per aggiornare un record esistente occorre conoscerne l'ID. Una volta recuperato, si può usare un metodo PUT o PATCH: 


curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records/<DNS_RECORD_ID>"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"   --data '{
    "type": "A",
    "name": "www",
    "content": "203.0.113.20",
    "ttl": 300,
    "proxied": false
  }'

Per eliminare il record: 


curl -X DELETE "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/dns_records/<DNS_RECORD_ID>"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"

Gestione del firewall e delle regole di sicurezza

Le API consentono di configurare firewall rules, IP Access Rules, rate limiting e molte altre funzionalità di sicurezza. Questo è cruciale per integrare Cloudflare con sistemi di sicurezza esistenti o per reagire automaticamente a incidenti.

Firewall Rules

Le Firewall Rules permettono di definire condizioni complesse per consentire, bloccare o sfidare (challenge) il traffico. La definizione avviene tramite espressioni simili a quelle utilizzate nella dashboard. 


{
  "filter": {
    "expression": "(ip.src in {192.0.2.1 198.51.100.0/24})",
    "paused": false,
    "description": "Blocca IP sospetti"
  },
  "action": "block"
}

Questa struttura JSON verrebbe inviata a un endpoint dedicato alla creazione di firewall filters e rules, tipicamente con metodo POST.

API per performance e caching

Attraverso le API si possono controllare impostazioni di caching, ottimizzazioni delle immagini, minificazione e compressione automatica. Ad esempio, è possibile svuotare selettivamente la cache di determinati asset o dell'intero sito.

Purge della cache

Per eliminare l'intera cache di una zona: 


curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"   --data '{
    "purge_everything": true
  }'

Per un purge selettivo su specifici URL: 


curl -X POST "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/purge_cache"   -H "Authorization: Bearer <API_TOKEN>"   -H "Content-Type: application/json"   --data '{
    "files": [
      "https://www.esempio.com/css/stile.css",
      "https://www.esempio.com/js/app.js"
    ]
  }'

Cloudflare Workers e API correlate

I Workers permettono di eseguire codice JavaScript alla periferia della rete di Cloudflare. Le API consentono di gestire script, impostazioni di routing e KV storage, in modo da integrare deploy automatizzati nelle pipeline CI/CD.

Distribuire uno script Worker

Uno script Worker può essere caricato tramite una richiesta PUT su un endpoint specifico per la zona o l'account, con il codice JavaScript passato nel corpo della richiesta. In molti casi si preferisce utilizzare strumenti come Wrangler, che a loro volta sfruttano le API di Cloudflare, ma è possibile interagire direttamente con le API REST per casi d'uso avanzati. 


addEventListener("fetch", event => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  return new Response("Hello from Cloudflare Worker", {
    status: 200,
    headers: { "Content-Type": "text/plain" }
  });
}

Lo script viene poi associato a determinate route o a un dominio intero tramite ulteriori chiamate API.

Paginazione, filtri e ordinamento

Molti endpoint che restituiscono liste (zone, record DNS, log, eccetera) implementano un meccanismo di paginazione. Di solito è possibile specificare parametri come:

  • page: indice della pagina.
  • per_page: numero di elementi per pagina.
  • Parametri di filtro (ad esempio nome, stato, tipo).
  • Opzioni di ordinamento, quando supportate.

La risposta includerà metadati sul numero totale di pagine, sul numero di risultati e sul cursore corrente, consentendo di iterare programmaticamente sull'intero dataset.

Gestione degli errori e best practice

Le risposte di errore includono tipicamente un codice HTTP descrittivo e un array errors con codici interni Cloudflare e messaggi testuali. È buona norma gestire almeno:

  • Codici 4xx per errori del client (autenticazione, permessi, parametri errati).
  • Codici 5xx per errori temporanei lato Cloudflare.

Alcune best practice nell'uso delle API di Cloudflare:

  • Utilizzare API Token con permessi minimi necessari.
  • Archiviare le credenziali in modo sicuro (ad esempio in un secret manager) ed evitare di inserirle nel codice sorgente.
  • Implementare meccanismi di retry con backoff esponenziale per errori 5xx o di rete.
  • Limitare la frequenza delle chiamate per rispettare eventuali rate limit.
  • Monitorare le risposte e i log per individuare tempestivamente errori o comportamenti anomali.

Integrazione con linguaggi e strumenti comuni

Sebbene sia sempre possibile usare curl o librerie HTTP generiche, nella pratica si integrano le API di Cloudflare in applicazioni e script nei linguaggi più diffusi. Ad esempio in Python: 


import requests

API_TOKEN = "..."  # recupera da variabile d'ambiente o secret manager
ZONE_ID = "..."

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

url = f"https://api.cloudflare.com/client/v4/zones/{ZONE_ID}/dns_records"

response = requests.get(url, headers=headers)
data = response.json()

if data.get("success"):
    for record in data.get("result", []):
        print(record["name"], record["type"], record["content"])
else:
    print("Errore nella chiamata API:", data.get("errors"))

Approcci analoghi sono possibili con Node.js, Go, PHP e altri linguaggi, sfruttando librerie HTTP idiomatiche e gestendo l'autenticazione tramite header.

Conclusione

Le API di Cloudflare costituiscono uno strumento potente per automatizzare la gestione dell'infrastruttura web, migliorare sicurezza e performance e integrare le funzionalità della piattaforma nei propri processi aziendali. Partendo dalle operazioni di base su zone e record DNS, passando per firewall, caching e Workers, è possibile costruire pipeline completamente automatizzate e altamente affidabili. La chiave è comprendere bene il modello di autenticazione, la struttura delle richieste e l'interpretazione delle risposte, adottando al contempo buone pratiche di sicurezza e osservabilità.

Torna su