Une bonne API paraît ennuyeuse, dans le meilleur sens : des URL prévisibles, des erreurs honnêtes, des schémas petits et stables, aucune surprise. Ce sont les principes qui façonnent l'API serveur de Noxyr, empruntés aux standards du secteur derrière Stripe, Resend, OpenAI et l'API officielle de Discord.
1. URL versionnées
Chaque endpoint se trouve sous /api/v1/. Quand nous ajoutons des changements incompatibles, ils arrivent sous /api/v2/ : les anciennes intégrations continuent de fonctionner. Discord fait la même chose avec /api/v10/. Si votre API n'est pas versionnée, chaque changement de schéma devient un ticket de support client.
2. Des ressources d'abord, des actions ensuite
Les endpoints de Noxyr sont nommés d'après des noms communs, server, tickets, activity, invoices, reviews, giveaways. Tous en lecture seule, tous en GET. Quand nous ajouterons des écritures, elles seront en POST/PATCH/DELETE sur les mêmes ressources. Cela suit proprement les conventions REST et garde le modèle mental minuscule.
3. Jetons Bearer, un seul secret
L'authentification se fait par Authorization: Bearer nxr_.... Pas de requêtes signées, pas de flux OAuth pour les données serveur en lecture seule. Les API destinées aux développeurs convergent vers ce modèle parce qu'il fonctionne partout : curl, navigateurs, Postman, edges serverless. Discord utilise aussi des jetons bearer pour les utilisateurs autorisés via OAuth ; le modèle est universel.
4. Ne stocker que des empreintes
Chaque clé Noxyr est hachée en SHA-256 côté serveur. La valeur brute n'est affichée qu'une fois, à la génération, et jamais plus. Si notre base de données fuitait, aucune clé ne serait utilisable. Stripe, GitHub, Resend et tous les fournisseurs d'API bien gérés font de même : un stockage de clés réversible est un signal d'alarme.
5. Des droits fins
Une clé, six interrupteurs indépendants. Les avis sont des données publiques ; les ventes sont privées. Les séparer permet de partager une clé réservée aux avis avec un partenaire marketing, et de garder les chiffres de revenus derrière un autre interrupteur. Les changements de droits prennent effet immédiatement (vérifiés à chaque requête), donc la révocation ne nécessite pas de renouveler la clé.
6. Des réponses d'erreur honnêtes
Chaque erreur est un JSON avec un code machine stable et un message lisible :
{ "error": "scope_disabled", "message": "The \"tickets\" scope is turned off for this key. Enable it on the dashboard API page." }Des codes lisibles par machine facilitent les nouvelles tentatives et les tableaux de bord. Des messages lisibles par un humain accélèrent le débogage. Les recherches « discord increased api errors » de juillet 2026 (tendance « breakout » sur Google Trends) montrent ce qui arrive quand les erreurs sont opaques : les utilisateurs devinent.
7. Séries temporelles sans trous
L'endpoint /api/v1/activity renvoie chaque jour de la plage demandée, même quand le nombre est zéro. Les frontends n'ont pas à combler les trous ; les graphiques ne sautent pas entre des dates éparses. C'est un petit confort qui apporte un gain de qualité de vie énorme.
8. Limites de débit via les en-têtes
Chaque réponse contient des en-têtes RateLimit-* pour que les clients puissent ralentir avant d'atteindre le 429. C'est le format standardisé du brouillon IETF, la même forme que GitHub et d'autres API modernes : toute bibliothèque cliente existante qui le gère fonctionne directement.
9. CORS permissif pour les données en lecture seule
Les endpoints en lecture seule envoient Access-Control-Allow-Origin: *. Comme c'est la clé qui authentifie, et non l'origine, ouvrir le CORS ne coûte rien en sécurité et permet aux outils du navigateur d'appeler l'API directement, sans proxy ni contournement localhost.
10. Schémas petits et stables
Chaque réponse tient sur un écran. Pas d'objets imbriqués optionnels, pas de champs qui n'apparaissent que lorsqu'un flag de fonctionnalité est activé. Les petits schémas se mettent en cache, se testent facilement et se typent sans peine en TypeScript.
Voir en pratique : tutoriel de l'API serveur. Et quand Discord lui-même dysfonctionne, ce que signifient réellement ces erreurs de l'API Discord.