Aller au contenu principal
CaptainDNS

Changelog de l'API publique

Cette page liste les changements majeurs de l'API publique CaptainDNS. Les ajouts non breaking (nouveaux endpoints, nouveaux champs optionnels) sont documentés ici sans préavis formel. Les changements de rupture sont annoncés au minimum 30 jours avant leur déploiement via cette même page et par email aux détenteurs de clés actives.

Politique de versionnage

  • Rétrocompatibilité : les ajouts de champs optionnels et les nouveaux endpoints ne cassent pas les clients existants.
  • Dépréciations : un champ ou un endpoint déprécié reste fonctionnel pendant au moins 6 mois après l'annonce.
  • Ruptures : les breaking changes sont annoncés 30 jours à l'avance et déployés sur une nouvelle URL versionnée (par exemple /public/v2/*). L'URL de V1 reste opérationnelle pendant la période de migration.
  • Identifiant de version : la spécification OpenAPI porte son propre numéro de version (info.version). Le numéro majeur suit l'URL versionnée, le mineur suit les ajouts rétro-compatibles.

Version 0.4.0 - 2026-07-21

Modifié

  • POST /public/v1/certificates/csr/parse passe de la famille mail:read à la famille web:read. Un CSR n'a rien de spécifiquement mail : l'endpoint rejoint url/check, page/crawl-check, phishing/check, http/headers-check, http/hsts-check et certificates/ssl/check. Aucune clé existante ne casse : pendant la période de transition, une clé portant mail:read ou web:read est acceptée. L'usage du seul scope mail:read est journalisé et ce scope hérité sera retiré à la fin de la transition, annoncée ici 30 jours à l'avance. Action à prévoir : créez vos nouvelles clés avec web:read, et ajoutez web:read aux clés existantes qui appellent cet endpoint.
  • Coût de POST /public/v1/certificates/csr/parse porté de 1 à 2 crédits. L'endpoint ne se contente plus de décoder un CSR : il rend un verdict de conformité adossé aux CA/Browser Forum Baseline Requirements, à la Mozilla Root Store Policy et aux RFC applicables, avec détection ROCA (CVE-2017-15361), détection de clé faible Debian (CVE-2008-0166) et empreinte SPKI SHA-256. Ce tarif l'aligne sur les autres endpoints qui rendent un diagnostic structuré (dane/lookup, bimi/lookup, rdap/lookup, ip/whois, certificates/ssl/check). Une hausse de coût ne provoque aucune erreur d'appel, mais elle double la consommation de crédits de toute intégration qui utilise cet endpoint : revoyez votre dimensionnement de quota avant de vous exposer à un dépassement.

Version 0.3.1 - 2026-05-19

Ajouté

  • POST /public/v1/dmarc/validate : enrichissement de la réponse avec scoring et recommandations. Nouveaux champs additifs et optionnels : state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. Le contrat existant (DMARCAnalysis au niveau racine) est strictement préservé. Coût inchangé (1 crédit), scope inchangé (mail:read).

Version 0.3.0 - 2026-04-14

Modifié

  • Payload webhook : passage à schema_version: "2". Nouveaux champs event_id, delivery_id, attempt. User-Agent désormais CaptainDNS-Webhook/2.0.
  • Headers ajoutés sur chaque POST : X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (format n/6), X-CaptainDNS-Event-Type. Les headers X-CaptainDNS-Signature et X-CaptainDNS-Timestamp restent inchangés.
  • Retry policy : si votre endpoint renvoie 5xx, 408, 429 ou un timeout/erreur réseau, 6 tentatives avec backoff 10s, 1min, 10min, 1h, 6h, 24h. Les autres 4xx passent immédiatement en failed_permanent sans retry.
  • event_id stable sur toutes les tentatives et les rejeux : clé de déduplication recommandée côté récepteur.

Version 0.2.0 - 2026-04-09

Ajouté

  • 51 endpoints publics sous /public/v1/* couvrant DNS, mail, web et texte :
    • DNS : resolve, resolve/propagation, dnssec/check, ip/whois, ip/nslookup, ip/netmask, rdap/lookup, domain/dns-check.
    • Mail : spf/lookup, spf/validate, dkim/lookup, dkim/validate, dmarc/lookup, dmarc/validate, dmarc/generate, dmarcbis/check, dmarcbis/migrate, dmarc/report/analyze, bimi/lookup, bimi/validate, bimi/logo/lookup, mta-sts/lookup, tls-rpt/lookup, dane/lookup, blacklist/ip, smtp/check, mail/header-audit, mail/header-analyze, mail/domain-check, deliverability/score, certificates/csr/parse, certificats/bimi/parse, certificats/bimi/lookup.
    • Web : url/check, page/crawl-check, phishing/check.
    • Text : text/lower, text/upper, text/stats, text/slug, text/base64/encode, text/base64/decode, text/password/generate, text/urlencode, text/urldecode, text/json/format, text/json/to-yaml, text/yaml/format, text/yaml/to-json, text/hash, text/regex/test.
  • Gestion des clés API depuis le dashboard CaptainDNS : liste, création, révocation, rotation et consultation de l'usage.
  • Schéma OpenAPI PublicAPIError avec 10 codes canoniques pour toutes les erreurs de l'API publique.
  • Header Idempotency-Key style Stripe, replay sur 24 heures, conflit 409 IDEMPOTENCY_CONFLICT si body divergent.
  • Headers X-Credits-Limit/Remaining/Consumed retournés sur chaque réponse réussie.
  • Headers RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (ce dernier est écrit uniquement en cas de refus 429).
  • Header X-Request-Id retourné sur toutes les réponses pour faciliter le support.
  • 5 plans de facturation : Free, Starter, Pro, Business, Enterprise, avec quotas et overage configurés par tier.
  • Facturation de l'overage opt-in avec plafond budgétaire mensuel configurable depuis le dashboard.
  • Notification channels (webhooks, Slack) côté dashboard profil, avec signature HMAC-SHA256 optionnelle et 22 types d'événements. Voir la page dédiée.

Non livré en V1

  • Webhooks d'API publique signés par clé (table webhook_endpoints) pour pousser les événements du compte vers vos systèmes.

Comment être informé des mises à jour

  • Blog CaptainDNS : les releases majeures sont relayées en articles dédiés sur captaindns.com/fr/blog.
  • Email : les détenteurs de clés actives reçoivent une notification automatique pour tout changement de rupture.
  • Cette page : tout ajout ou correctif est consigné ici, par ordre antéchronologique.
  • Spécification OpenAPI : le champ info.version est incrémenté à chaque release. Surveiller sa valeur permet de déclencher vos régénérations de SDK.

Prochaine étape : revenez au quickstart pour commencer à intégrer, ou explorez la référence OpenAPI pour voir tous les schémas en détail.