Un'API buona sembra noiosa, nel senso migliore: URL prevedibili, errori chiari, schemi piccoli e stabili, nessuna sorpresa. Sono questi i principi che danno forma alla Noxyr Server API, presi dagli standard del settore usati da Stripe, Resend, OpenAI e dalla API ufficiale di Discord.
1. URL versionati
Ogni endpoint vive sotto /api/v1/. Quando introduciamo modifiche non compatibili, finiscono sotto /api/v2/: le vecchie integrazioni continuano a funzionare. Discord fa lo stesso con /api/v10/. Se la tua API non è versionata, ogni modifica allo schema diventa un ticket di assistenza.
2. Prima le risorse, poi le azioni
Gli endpoint di Noxyr prendono il nome da sostantivi: server, tickets, activity, invoices, reviews, giveaways. Sono tutti in sola lettura, tutti GET. Quando aggiungeremo le scritture, saranno POST/PATCH/DELETE sulle stesse risorse. Questo si allinea bene alle convenzioni REST e mantiene il modello mentale minimo.
3. Bearer token, un solo segreto
L'autenticazione è Authorization: Bearer nxr_.... Niente richieste firmate, niente flusso OAuth per i dati di sola lettura del server. Le API moderne rivolte agli sviluppatori convergono su questo perché funziona ovunque: curl, browser, Postman, edge serverless. Anche Discord usa i bearer token per gli utenti autorizzati via OAuth; il modello è universale.
4. Salvare solo gli hash
Ogni chiave Noxyr viene salvata lato server come hash SHA-256. Il valore reale viene mostrato una sola volta, al momento della generazione, e mai più. Se il nostro database venisse esposto, nessuna chiave sarebbe utilizzabile. Stripe, GitHub, Resend e tutti gli altri fornitori di API ben gestiti fanno lo stesso: una memorizzazione delle chiavi reversibile è un campanello d'allarme.
5. Permessi granulari
Una chiave, sei interruttori indipendenti. Le recensioni sono dati pubblici; le vendite sono private. Separarli significa che puoi condividere con un partner di marketing una chiave solo per le recensioni e tenere i numeri delle entrate dietro un altro interruttore. Le modifiche ai permessi hanno effetto subito (verificate a ogni richiesta), quindi revocare un accesso non richiede la rotazione della chiave.
6. Risposte di errore chiare
Ogni errore è un JSON con un codice stabile leggibile dalle macchine e un messaggio leggibile dalle persone:
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }I codici leggibili dalle macchine rendono facili i tentativi ripetuti e le dashboard. I messaggi leggibili dalle persone rendono rapido il debug. Le ricerche di "discord increased api errors" nel luglio 2026 (picco di "breakout" su Google Trends) mostrano cosa succede quando gli errori sono opachi: gli utenti tirano a indovinare.
7. Serie temporali riempite con zeri
L'endpoint /api/v1/activity restituisce ogni giorno dell'intervallo richiesto, anche quando il conteggio è zero. I frontend non devono riempire i buchi; i grafici non saltano tra date sparse. È un piccolo vantaggio con un enorme beneficio in termini di qualità della vita.
8. Limiti di frequenza con header
Ogni risposta contiene header RateLimit-* così i client possono rallentare prima di arrivare a un 429. È il formato standard della bozza IETF, con la stessa struttura di GitHub e di altre API moderne, quindi ogni libreria client esistente che lo supporta funziona subito.
9. CORS permissivo per i dati di sola lettura
Gli endpoint di sola lettura inviano Access-Control-Allow-Origin: *. Poiché ad autenticare è la chiave, non l'origine, aprire il CORS non costa nulla in termini di sicurezza e permette agli strumenti nel browser di chiamare l'API direttamente, senza proxy né workaround con localhost.
10. Schemi piccoli e stabili
Ogni risposta sta in una sola schermata. Niente oggetti annidati opzionali, niente campi che compaiono solo quando una funzione è attiva. Gli schemi piccoli sono memorizzabili nella cache, testabili e facili da tipizzare in TypeScript.
Guarda come si applica nella pratica: tutorial sulla Server API. E quando è Discord stesso a comportarsi male, cosa significano davvero quegli errori dell'API Discord.