Méthodologie de l’API

Chaque conversion que Convertitive propose est aussi un point de terminaison JSON sous /api/v1/. L’API est active depuis FAZ 4 et sert les mêmes facteurs et formules que l’interface — si un résultat est correct sur la page, il l’est aussi depuis l’API.

Conception des points de terminaison

Style REST. Le chemin décrit la ressource, la chaîne de requête porte les paramètres. Exemples :

• 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 — liste toutes les catégories d’unités
• GET /api/v1/health/ — santé du service (disponibilité + version)

Pas de corps POST. Toutes les entrées sont des paramètres de requête. Idempotent, cacheable, compatible navigateur.

Enveloppe de réponse

Chaque réponse réussie utilise la même structure :

{
  "ok": true,
  "data": { /* spécifique au point de terminaison */ },
  "meta": { /* métadonnées optionnelles : rateDate, factor, etc. */ }
}

Chaque réponse d’erreur :

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAM",
    "message": "Explication lisible par l'humain",
    "param": "from"
  }
}

Codes de statut HTTP standard : 200 pour le succès, 400 pour les erreurs d’entrée, 404 pour les catégories/unités inconnues, 500 uniquement quand quelque chose a vraiment échoué. Ne traitez pas les 4xx comme réessayables.

Politique CORS

Access-Control-Allow-Origin: *sur chaque point de terminaison API. Utilisez-le depuis n’importe quelle origine, y compris le développement local. Aucun preflight nécessaire car chaque requête est un GET sans en-têtes personnalisés — les règles de requête simple s’appliquent.

Aucune authentification

Pas de clé API, pas d’OAuth, pas de requêtes signées. Chaque point de terminaison est anonyme. Trois raisons :

1. Les données ne valent pas la peine d’être restreintes. Les facteurs de conversion d’unités sont dans le domaine public. Les taux ECB sont republics publiquement par ~20 services. Faire payer pour eux reviendrait à facturer les données de quelqu’un d’autre.
2. L’authentification ajoute des frictions pour le cas d’utilisation dominant. Un développeur testant une fonctionnalité, un étudiant scriptant une comparaison de devoir, un hobbyiste construisant un tracker — aucun d’eux ne veut s’inscrire d’abord.
3. Les limites de débit gèrent les abus.Les valeurs par défaut de Cloudflare plus le coût computationnel trivial de chaque conversion signifient que quelqu’un essayant de scraper Convertitive peut obtenir les données plus vite en miroir du flux ECB public directement.

Versionnement

Le préfixe /api/v1/est intentionnel. Quand l’enveloppe de réponse ou la forme d’erreur change de façon significative, un /api/v2/ est déployé en parallèle ; la v1 est supportée pendant au moins 12 mois après le lancement de la v2.

Les corrections de bugs et les changements additifs (nouveaux points de terminaison, nouveaux champs optionnels dans les réponses) sont déployés en continu sans changement de version.

L’API elle-même est agnostique aux paramètres régionaux — les chiffres, symboles d’unités et codes ISO ne se traduisent pas — mais les pages éditoriales qui la documentent, oui. Nous publions des variantes localisées sous des préfixes de chemin par paramètre régional et les signalons aux moteurs de recherche avec des annotations hreflang générées à partir d’un registre de traduction central, afin qu’un lecteur français de /fr/methodologie/api/ obtienne le même contrat JSON décrit dans sa langue.

Fraîcheur des taux de change

Les points de terminaison de devises retournent le taux interbancaire ECB mis en cache pendant une heure via ISR. Le champ meta.rateDate dans chaque réponse de devise vous indique quand le taux a été publié (toujours un jour ouvrable ECB récent). Pour les travaux en temps réel à haute précision, obtenez les taux de votre courtier ; pour tout le reste, notre cache convient.

Ce que nous n’ajouterons pas à l’API

• Points de terminaison POST pour les opérations avec état (nous n’avons pas d’état).
• Points de terminaison en masse (bouclez sur les singletons ; c’est assez rapide).
• WebSocket / streaming (les données ne changent pas assez fréquemment pour justifier le protocole).
• Clés API / niveaux payants (voir “aucune authentification” ci-dessus).

Détails de l’algorithme : cycle de vie de la requête de bout en bout

Chaque requête API suit le même pipeline en six étapes pour que le comportement observable soit uniforme d’un point de terminaison à l’autre. Les étapes, dans l’ordre :

1. Routage en périphérie.Cloudflare fait correspondre la requête à la carte de routes mise en cache et sert soit la réponse mise en cache (devise, paires d’unités populaires), soit transfère le manque à la fonction Next.js. Latence p50 avec cache : ~25 ms ; p50 sans cache : ~70 ms.
2. Méthode & preflight CORS.Rejeter les méthodes non-GET avec 405. Appliquer l’en-tête Access-Control-Allow-Origin: * sur chaque réponse selon la spécification WHATWG Fetch.
3. Validation de schéma. Analyser les paramètres de requête avec un schéma de style Zod. Les paramètres manquants ou mal formés retournent 400 avec { ok: false, error: { code: "INVALID_PARAM", param } }.
4. Résoudre la conversion.Rechercher la conversion cible dans le même registre que l’interface utilise (unités, devise, couleur, image …). Pour la devise, lire le cache ISR ; pour l’unité/couleur, la fonction est un calcul pur déterministe.
5. Formater l’enveloppe. Toujours { ok: true, data, meta }. Les nombres sont sérialisés comme des nombres JSON (pas des chaînes) selon la RFC 8259 pour l’analyse native par les consommateurs.
6. En-têtes de cache. Les réponses de devise reçoivent Cache-Control: public, max-age=3600, stale-while-revalidate=86400; les réponses d’unité/ couleur reçoivent max-age=31536000, immutable car les mathématiques ne changent jamais.

Sources & références

La conception de l’API suit la sémantique HTTP de la RFC 9110 et les règles de mise en cache HTTP de la RFC 9111. Le comportement CORS suit la spécification WHATWG Fetch. Les corps de réponse utilisent JSON UTF-8 selon la RFC 8259. La raison d’être de l’enveloppe d’erreur remonte à la RFC 7807 (Problem Details). Voir le bloc Sources au bas de la page pour les spécifications canoniques.

Hypothèses & limites

• GET uniquement.Pas de POST/PUT/DELETE. Tout ce qui nécessite un corps aurait besoin d’une conception différente et très probablement d’une authentification.
• Aucune analyse de corps de requête.Toutes les entrées sont des paramètres de requête avec encodage URL. Les entrées supérieures à ~2 Ko risquent d’atteindre les limites de longueur d’URL sur les intermédiaires.
• Les limites de débit sont au niveau de la périphérie réseau, pas par clé API. Les clients à fort volume partageant un NAT peuvent partager le même quota ; reproduisez les données pertinentes localement pour les charges de production.
• Pas de SLA.L’API est au mieux-effort. Mettez en cache agressivement et traitez les 5xx comme transitoires.
• Pas de WebSocket / SSE structuré. Le polling est correct car les données sous-jacentes se mettent à jour au maximum toutes les heures.
• JSON uniquement, pas de XML / msgpack. La négociation Acceptn’est pas implémentée.
• Les horodatages sans fuseau horaire dans certaines réponses legacy.Tous les nouveaux points de terminaison émettent ISO 8601 avec un décalage explicite ; les champs pré-v1.4 sont en UTC par convention mais manquent d’un suffixe Z.

Documentation en direct sur /api/.