Zum Hauptinhalt springen
CaptainDNS

Changelog der Public API

Diese Seite listet die wichtigsten Änderungen der CaptainDNS Public API. Nicht brechende Ergänzungen (neue Endpunkte, neue optionale Felder) werden hier ohne formelle Ankündigung dokumentiert. Breaking Changes werden mindestens 30 Tage vor dem Deployment angekündigt, hier und per E-Mail an aktive Schlüsselinhaber.

Versionierungsregeln

  • Rückwärtskompatibilität: das Hinzufügen optionaler Felder und neuer Endpunkte bricht keine bestehenden Clients.
  • Deprecations: ein abgekündigtes Feld oder ein abgekündigter Endpunkt bleibt mindestens 6 Monate nach der Ankündigung funktionsfähig.
  • Brüche: Breaking Changes werden 30 Tage im Voraus angekündigt und unter einer neuen versionierten URL (z. B. /public/v2/*) deployt. Die V1-URL bleibt während der Migrationsperiode erreichbar.
  • Versionsidentifikator: die OpenAPI-Spezifikation trägt eine eigene Versionsnummer (info.version). Die Major-Nummer folgt der versionierten URL, die Minor-Nummer folgt den rückwärtskompatiblen Ergänzungen.

Version 0.4.0 - 2026-07-21

Geändert

  • POST /public/v1/certificates/csr/parse wechselt von der Familie mail:read in die Familie web:read. Ein CSR hat nichts spezifisch Mail-Bezogenes: der Endpunkt reiht sich neben url/check, page/crawl-check, phishing/check, http/headers-check, http/hsts-check und certificates/ssl/check ein. Kein bestehender Schlüssel bricht: während der Übergangsphase wird ein Schlüssel mit mail:read oder web:read akzeptiert. Die alleinige Nutzung von mail:read wird protokolliert, und dieser geerbte Scope wird entfernt, sobald die Übergangsphase endet; die Abkündigung erfolgt hier 30 Tage im Voraus. Geplante Aktion: erstellen Sie neue Schlüssel mit web:read und ergänzen Sie web:read bei bestehenden Schlüsseln, die diesen Endpunkt aufrufen.
  • Kosten von POST /public/v1/certificates/csr/parse von 1 auf 2 Credits erhöht. Der Endpunkt dekodiert nicht mehr nur einen CSR: Er liefert ein Konformitätsurteil auf Basis der CA/Browser Forum Baseline Requirements, der Mozilla Root Store Policy und der anwendbaren RFC, inklusive ROCA-Erkennung (CVE-2017-15361), Erkennung schwacher Debian-Schlüssel (CVE-2008-0166) und SHA-256-SPKI-Fingerabdruck. Dieser Preis richtet ihn an den anderen Endpunkten aus, die eine strukturierte Diagnose liefern (dane/lookup, bimi/lookup, rdap/lookup, ip/whois, certificates/ssl/check). Eine Kostenerhöhung lässt keinen Aufruf fehlschlagen, aber sie verdoppelt den Credit-Verbrauch jeder Integration, die diesen Endpunkt nutzt: Prüfen Sie Ihre Kontingentplanung, bevor Sie in eine Überschreitung laufen.

Version 0.3.1 - 2026-05-19

Hinzugefügt

  • POST /public/v1/dmarc/validate: Antwort jetzt mit Scoring und Empfehlungen angereichert. Neue optionale Felder: state, score, score_band, verdict_headline, verdict_sub, score_factors, score_breakdown, recommendations, passed_checks, parsed_tags. Der bestehende Vertrag (DMARCAnalysis auf Root-Ebene) bleibt strikt erhalten. Kosten unverändert (1 Credit), Scope unverändert (mail:read).

Version 0.3.0 - 2026-04-14

Geändert

  • Webhook-Payload: jetzt mit schema_version: "2". Neue Felder event_id, delivery_id, attempt. User-Agent ist jetzt CaptainDNS-Webhook/2.0.
  • Neue Header bei jedem POST: X-CaptainDNS-Event-ID, X-CaptainDNS-Delivery-ID, X-CaptainDNS-Attempt (Format n/6), X-CaptainDNS-Event-Type. Die bestehenden Header X-CaptainDNS-Signature und X-CaptainDNS-Timestamp bleiben unverändert.
  • Wiederholungsstrategie: wenn Ihr Endpoint 5xx, 408, 429 oder einen Timeout/Netzwerkfehler zurückgibt, werden 6 Versuche mit Backoff 10s, 1min, 10min, 1h, 6h, 24h durchgeführt. Andere 4xx-Antworten gehen sofort in failed_permanent ohne Wiederholung.
  • Stabile event_id über alle Versuche und manuelle Wiederholungen: empfohlener Deduplizierungsschlüssel auf Empfängerseite.

Version 0.2.0 - 2026-04-09

Hinzugefügt

  • 51 öffentliche Endpunkte unter /public/v1/* für DNS, Mail, Web und Text:
    • 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.
  • Verwaltung von API-Schlüsseln über das CaptainDNS-Dashboard: Auflisten, Erstellen, Widerrufen, Rotieren und Usage-Abfrage.
  • OpenAPI-Schema PublicAPIError mit 10 kanonischen Codes für alle Fehler der Public API.
  • Stripe-Style Idempotency-Key-Header, 24-Stunden-Replay, 409 IDEMPOTENCY_CONFLICT bei abweichendem Body.
  • Header X-Credits-Limit/Remaining/Consumed bei jeder erfolgreichen Antwort.
  • Header RateLimit-Policy, X-RateLimit-Limit, X-RateLimit-Remaining (Letzteres wird nur bei einer 429-Ablehnung gesetzt).
  • Header X-Request-Id bei jeder Antwort zur Erleichterung des Supports.
  • 5 Abrechnungspläne: Free, Starter, Pro, Business, Enterprise mit Kontingenten und Overage pro Tier.
  • Opt-in-Überschreitungsabrechnung mit konfigurierbarem monatlichem Budgetlimit im Dashboard.
  • Notification Channels (Webhooks, Slack) im Profil-Dashboard, mit optionaler HMAC-SHA256-Signatur und 22 Ereignistypen. Siehe die dedizierte Seite.

In V1 nicht enthalten

  • Per Schlüssel signierte Public-API-Webhooks (Tabelle webhook_endpoints), um Konto-Ereignisse an Ihre Systeme zu pushen.

Auf dem Laufenden bleiben

  • CaptainDNS-Blog: wichtige Releases werden in eigenen Beiträgen auf captaindns.com/de/blog veröffentlicht.
  • E-Mail: aktive Schlüsselinhaber erhalten eine automatische Benachrichtigung bei jedem Breaking Change.
  • Diese Seite: jede Ergänzung oder Korrektur wird hier chronologisch rückwärts festgehalten.
  • OpenAPI-Spezifikation: das Feld info.version wird bei jedem Release hochgezählt. Die Überwachung dieses Wertes ermöglicht automatische Neugenerierungen Ihrer SDKs.

Nächster Schritt: zurück zum Quickstart, um mit der Integration zu beginnen, oder die OpenAPI-Referenz für alle Schemas im Detail erkunden.