Metodologia API

Ogni conversione che Convertitive offre è anche un endpoint JSON sotto /api/v1/. L’API è attiva dalla versione FAZ 4 e serve gli stessi fattori e formule dell’interfaccia utente — se un risultato è corretto sulla pagina, è corretto anche dall’API.

Design degli endpoint

Stile REST. Il percorso descrive la risorsa, la query string porta i parametri. Esempi:

• GET /api/v1/convert/unit?category=length&from=cm&to=inches&value=5
• GET /api/v1/convert/currency?from=USD&to=EUR&value=100
• GET /api/v1/convert/color?from=hex&to=rgb&value=%23FF6B35
• GET /api/v1/categories — elenca ogni categoria di unità
• GET /api/v1/health/ — stato del servizio (uptime + versione)

Nessun corpo POST. Tutti gli input sono parametri di query. Idempotente, memorizzabile nella cache, compatibile con il browser.

Envelope di risposta

Ogni risposta di successo usa la stessa struttura:

{
  "ok": true,
  "data": { /* specifico per endpoint */ },
  "meta": { /* metadati opzionali: rateDate, factor, ecc. */ }
}

Ogni risposta di errore:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Spiegazione leggibile dall'uomo",
    "param": "from"
  }
}

Codici di stato HTTP standard: 200 per il successo, 400 per errori di input, 404 per categorie/unità sconosciute, 500 solo quando qualcosa si è davvero rotto. Non trattare i 4xx come ritentabili.

Politica CORS

Access-Control-Allow-Origin: *su ogni endpoint API. Usalo da qualsiasi origine, incluso lo sviluppo locale. Non è necessario il preflight perché ogni richiesta è GET senza intestazioni personalizzate — si applicano le regole della richiesta semplice.

Nessuna autenticazione

Nessuna chiave API, nessun OAuth, nessuna richiesta firmata. Ogni endpoint è anonimo. Tre ragioni:

1. I dati non sono abbastanza preziosi da bloccare. I fattori di conversione delle unità sono di pubblico dominio. I tassi BCE sono ripubblicati pubblicamente da ~20 servizi. Far pagare per loro significherebbe far pagare per i dati di qualcun altro.
2. L’autenticazione aggiunge attrito per il caso d’uso dominante. Uno sviluppatore che testa una funzionalità, uno studente che crea uno script per un confronto dei compiti, un hobbista che costruisce un tracker — nessuno di loro vuole registrarsi prima.
3. I limiti di velocità gestiscono gli abusi. I default di Cloudflare più il costo computazionale banale di ogni conversione significano che chiunque tenti di fare scraping di Convertitive può ottenere i dati più velocemente mirroring direttamente del feed pubblico BCE.

Versionamento

Il prefisso /api/v1/è intenzionale. Quando l’envelope di risposta o la forma degli errori cambia significativamente, viene rilasciato un /api/v2/ in parallelo; v1 è supportata per almeno 12 mesi dopo il lancio di v2.

Le correzioni di bug e le modifiche additive (nuovi endpoint, nuovi campi opzionali nelle risposte) vengono rilasciati continuamente senza un incremento della versione.

L’API stessa è agnostica alla lingua — numeri, simboli di unità e codici ISO non si traducono — ma le pagine editoriali che la documentano sì. Pubblichiamo varianti localizzate con prefissi di percorso per locale e le segnaliamo ai motori di ricerca con annotazioni hreflang generate da un registro di traduzione centrale, così un lettore spagnolo di /es/methodology/api/ ottiene lo stesso contratto JSON descritto nella loro lingua.

Freschezza del tasso di cambio

Gli endpoint di valuta restituiscono il tasso mid-market BCE memorizzato nella cache per un’ora tramite ISR. Il campo meta.rateDate in ogni risposta valutaria ti dice quando il tasso è stato pubblicato (sempre un recente giorno lavorativo BCE). Per il lavoro in tempo reale ad alta precisione, ottieni i tassi dal tuo broker; per tutto il resto, la nostra cache è sufficiente.

Cosa non aggiungeremo all’API

• Endpoint POST per operazioni con stato (non abbiamo stato).
• Endpoint bulk (cicla sui singleton; è abbastanza veloce).
• WebSocket / streaming (i dati non cambiano abbastanza frequentemente da giustificare il protocollo).
• Chiavi API / livelli a pagamento (vedi “nessuna autenticazione” sopra).

Dettagli dell’algoritmo: ciclo di vita della richiesta, dall’inizio alla fine

Ogni richiesta API esegue la stessa pipeline a sei fasi così che il comportamento osservabile è uniforme tra gli endpoint. Le fasi, in ordine:

1. Routing edge. Cloudflare abbina la richiesta alla mappa di route memorizzata nella cache e serve la risposta dalla cache (valuta, coppie di unità popolari) o inoltra il miss alla funzione Next.js. Latenza p50 cache-hit: ~25 ms; cache-miss p50: ~70 ms.
2. Metodo & preflight CORS.Rifiuta i metodi non-GET con 405. Applica l’intestazione Access-Control-Allow-Origin: * su ogni risposta secondo la specifica WHATWG Fetch.
3. Validazione dello schema. Analizza i parametri di query con uno schema stile Zod. I parametri mancanti o mal formati restituiscono 400 con { ok: false, error: { code: "INVALID_PARAM", param } }.
4. Risolvi la conversione.Cerca la conversione target nello stesso registro che usa l’interfaccia utente (unità, valuta, colore, immagine…). Per la valuta, leggi la cache ISR; per unità/colore, la funzione è un calcolo puro deterministico.
5. Formatta l’envelope. Sempre { ok: true, data, meta }. I numeri sono serializzati come numeri JSON (non stringhe) secondo RFC 8259 per l’analisi nativa del consumer.
6. Intestazioni cache. Le risposte valutarie ottengono Cache-Control: public, max-age=3600, stale-while-revalidate=86400; le risposte unità/colore ottengono max-age=31536000, immutable perché la matematica non cambia mai.

Fonti e riferimenti

Il design dell’API segue la semantica HTTP di RFC 9110 e le regole di caching HTTP di RFC 9111. Il comportamento CORS segue la specifica WHATWG Fetch. I corpi delle risposte usano JSON UTF-8 secondo RFC 8259. La logica dell’envelope degli errori trae spunto da RFC 7807 (Problem Details). Vedi il blocco Fonti nella parte inferiore della pagina per le specifiche canoniche.

Presupposti e limitazioni

• Solo GET. Nessun POST/PUT/DELETE. Qualsiasi cosa che richieda un corpo necessiterebbe di un design diverso e molto probabilmente di autenticazione.
• Nessun parsing del corpo della richiesta. Tutti gli input sono parametri di query con codifica URL. Gli input più grandi di ~2 KB rischiano di raggiungere i limiti di lunghezza URL sugli intermediari.
• I limiti di velocità sono a livello di rete edge, non per chiave API. I client ad alto volume che condividono un NAT possono condividere la stessa quota; mirrora i dati rilevanti localmente per carichi di produzione.
• Nessun SLA.L’API è best-effort. Memorizza aggressivamente nella cache e tratta i 5xx come transitori.
• Nessun WebSocket / SSE strutturato. Il polling va bene perché i dati sottostanti si aggiornano al massimo ogni ora.
• Solo JSON, nessun XML / msgpack. La negoziazione Accept non è implementata.
• Timestamp senza fuso orario in alcune risposte legacy. Tutti i nuovi endpoint emettono ISO 8601 con offset esplicito; i campi pre-v1.4 sono UTC per convenzione ma mancano del suffisso Z.

Documentazione live su /api/.