Question 1

Was ist die Cathopic-API?

Accepted Answer

Unsere API ist ein RESTful-Dienst, mit dem Sie die katholische Medienbibliothek von Cathopic direkt in Ihre Anwendungen integrieren können. Greifen Sie programmgesteuert auf Tausende von Bildern, Videos und Grafiken zu. Was Sie tun können Suchen und durchstöbern Sie unseren vollständigen Katalog Ressourcen lizenzieren Sie automatisch für Ihre Endnutzer Herunterladen in mehreren Formaten, optimiert für unterschiedliche Anwendungsfälle Auf umfangreiche Metadaten zugreifen, einschließlich Tags, Beschreibungen und liturgischer Informationen REST-Architektur Aufgebaut nach gängigen REST-Prinzipien: Basis-URL: https://api.cathopic.com Datenformat: JSON-Anfragen und -Antworten Authentifizierung: API-Schlüssel über den x-api-key-Header HTTP-Methode: POST für alle Endpunkte Vier zentrale Endpunkte POST /resources - Sucht im Katalog POST /resource - Ruft Details zu einem bestimmten Element ab POST /confirm - Lizenziert eine Ressource und gibt Download-URLs zurück POST /remove - Beendet die Lizenzierung, wenn sie nicht mehr benötigt wird (nur Website) Umfangreiche Dokumentation Alles, was Sie brauchen, ist online verfügbar: Interaktiver API-Referenzleitfaden: api.cathopic.com/docs Code-Beispiele in mehreren Sprachen Detaillierte Angaben zu Parametern Erste Schritte Kontaktieren Sie unser Team, um API-Zugriff anzufordern Erstellen Sie Ihren API-Schlüssel in Einstellungen → API Fügen Sie eine Zahlungsmethode für die nutzungsbasierte Abrechnung hinzu Beginnen Sie mit dem Aufbau Sehen Sie sich die anderen Fragen in diesem Abschnitt an, um Details zu Authentifizierung, Abrechnung und bewährten Vorgehensweisen zu erhalten. API-Lizenzvereinbarung Alle Nutzungen der API unterliegen unserer API-Lizenzvereinbarung. Wichtige Punkte, die Sie verstehen sollten: Nur digitale Nutzung: Der Inhalt darf nur in Web- und E-Mail-Umgebungen angezeigt werden Keine Dateidownloads: Endnutzer können die Originaldateien nicht herunterladen oder exportieren Untersagte Verwendungen: KI/ML-Training, Druckmaterialien und Offline-Nutzung sind streng verboten Abrechnung nach Nutzung: Zahlen Sie nur für die tatsächliche Inhaltsnutzung durch Ihre Endnutzer Mit der Nutzung der API akzeptieren Sie alle Bedingungen der Lizenzvereinbarung Bevor Sie die API integrieren: Prüfen Sie die vollständige API-Lizenzvereinbarung Verstehen Sie die Einschränkungen und Pflichten Stellen Sie sicher, dass Ihr Anwendungsfall den Anforderungen „nur digital“ entspricht Planen Sie Ihre Integration so, dass die Nutzung für die Abrechnung genau erfasst wird Weitere Details finden Sie unter: Was kann ich mit der API bauen? (enthält detaillierte Einschränkungen) Wie funktionieren Lizenzen über die API? (vollständige Lizenzdetails) Wie wird die API-Nutzung abgerechnet? (Erläuterung des Abrechnungsmodells)

Question 2

Was kann ich mit der API erstellen?

Accepted Answer

Die Cathopic-API ermöglicht es Ihnen, katholische visuelle Inhalte direkt in Ihre Anwendung, Ihre Website oder Ihre Plattform zu integrieren. Die Nutzung der API wird jedoch streng durch unsere API-Lizenzvereinbarung geregelt, die die Nutzung auf bestimmte digitale Umgebungen beschränkt. Was Sie erstellen können Kirchen- und Pfarrverwaltungs-Systeme Ermöglichen Sie es den Pfarreien, katholische Bildmotive in ihre Gemeindeblätter und Newsletter einzufügen Unterstützen Sie die Bewerbung von Veranstaltungen mit passenden visuellen Inhalten Stellen Sie liturgische Bilder bereit, die zum Kirchenjahr passen Erstellen Sie digitale Anzeigen für Pfarrankündigungen Plattformen für katholische Inhalte Entwickeln Sie Blogging-Plattformen für katholische Autorinnen und Autoren mit integrierten Bildmotiven Erstellen Sie katholische Nachrichten-Websites mit passenden visuellen Inhalten Entwickeln Sie Andachts-Apps mit täglichen Bildern und Gebeten Gestalten Sie katechetische Plattformen mit visuellen Lehrhilfen Tools für E-Mail-Marketing Ermöglichen Sie es den Seelsorgebereichen, Newsletter mit katholischen Bildmotiven zu erstellen Ermöglichen Sie es religiösen Organisationen, E-Mail-Kampagnen zu gestalten Stellen Sie Vorlagen mit integrierten Cathopic-Inhalten bereit Unterstützen Sie Fundraising-Kampagnen mit passenden visuellen Inhalten Website-Builder und CMS Integrieren Sie katholische Bildmotive in Website-Building-Plattformen Stellen Sie Content-Module für katholische Organisationen bereit Aktivieren Sie Drag-and-drop zur Auswahl von Bildern aus Cathopic Erstellen Sie Vorlagen, die speziell für katholische Dienste gedacht sind Veranstaltungs- und Social-Media-Management Helfen Sie Seelsorgebereichen, Social-Media-Grafiken zu erstellen (ohne Dateien herunterzuladen) Gestalten Sie Systeme für Veranstaltungseinladungen mit katholischen Bildmotiven Erstellen Sie Content-Kalender mit visuellen Motiven der liturgischen Zeit Ermöglichen Sie Organisationen, Beiträge mit passenden Bildern zu planen Wichtige Einschränkungen, die Sie einhalten müssen Die API-Lizenz verbietet ausdrücklich bestimmte Nutzungen. Verstöße gegen diese Einschränkungen können zu einer sofortigen Beendigung führen: ❌ KI-/ML-Training (DAUERHAFT VERBOTEN) Die API darf nicht verwendet werden, um KI-/ML-Modelle zu trainieren, feinzujustieren oder mit Daten zu versorgen Es dürfen keine Embeddings, Datensätze oder abgeleiteten Extrakte für KI erstellt werden Diese Einschränkung gilt dauerhaft, auch nach Beendigung der Vereinbarung Gilt für alle Formen von maschinellem Lernen und künstlicher Intelligenz ❌ Dateidownloads und Exporte Endnutzer können Inhalte nicht als Dateien herunterladen oder speichern Es darf keine Funktion „Download“ oder „Export“ bereitgestellt werden Der Inhalt muss bei Cathopic gehostet bleiben oder in einem autorisierten Cache Es dürfen nur URLs verwendet werden, die für das Web optimiert sind, nicht die Originaldateien ❌ Druck- und Offline-Nutzung Die API darf nicht für Drucksachen, Broschüren oder Plakate verwendet werden Keine Offline-Werbung oder physischen Produkte Streng auf digitale Web- und E-Mail-Umgebungen beschränkt Der Inhalt darf nicht in PDFs eingebunden werden, die zum Drucken gedacht sind ❌ Weiterverkauf und Weiterverbreitung Es dürfen keine Produkte erstellt werden, die Cathopic-Inhalte weiterverkaufen oder weiterverbreiten Es dürfen keine Stockfoto-Marktplätze mit unserer API erstellt werden Der Inhalt darf nicht als eigenständiges Produkt angeboten werden Der Inhalt muss als Teil eines größeren Dienstes integriert werden ❌ Änderung und abgeleitete Werke Der Inhalt darf nicht verändert, transformiert oder als abgeleitetes Werk erstellt werden Es dürfen keine Filter oder wesentlichen Änderungen angewendet werden Der Inhalt muss so angezeigt werden, wie er von der API bereitgestellt wird Grundlegendes Zuschneiden und Skalieren sind für Layout-Zwecke erlaubt Nur Web- und E-Mail-Umgebungen Inhalte, die über die API abgerufen werden, können nur verwendet werden in: Websites: öffentliche oder private Webseiten Webanwendungen: browserbasierte Tools und Plattformen E-Mail: Newsletter, Kampagnen und transaktionale E-Mails Blogs: Online-Content-Management-Systeme Web-Embeds: kontrollierte iframes oder über die API bereitgestellte Inhalte Wichtig: Der Inhalt muss ausschließlich in einer für das Web optimierten Auflösung angezeigt werden. Originale Dateien in hoher Auflösung sind niemals über die API zugänglich. Technische Anforderungen Ihre Anwendung muss: HTTPS verwenden: Alle API-Aufrufe und die Auslieferung der Inhalte müssen sicher sein Umgang mit Watermarks umsetzen: Beginnen Sie mit Inhalten mit Watermark; fordern Sie unmarkierte Inhalte nur dann an, wenn sie benötigt werden Nutzung genau nachverfolgen: Protokollieren Sie die gesamte Nutzung der Inhalte zu Abrechnungszwecken Endpoint „/confirm“ aufrufen: Wenn der Endnutzer sich dazu verpflichtet, Inhalte zu verwenden Endpoint „/remove“ aufrufen: Wenn der Inhalt nicht mehr verwendet wird (Abrechnung stoppt) Unbefugten Zugriff verhindern: Schützen Sie Ihre API-Zugangsdaten Rate Limits respektieren: Halten Sie die für Ihr Konto festgelegten Limits ein Ihre rechtlichen Pflichten Wenn Sie die API integrieren, müssen Sie: Ihre Nutzungsbedingungen aktualisieren, um Endnutzer zu informieren: Der Inhalt kann nicht heruntergeladen oder außerhalb Ihrer Anwendung verwendet werden Der Inhalt darf nicht für KI-/ML-Zwecke verwendet werden Der Inhalt ist Eigentum von Cathopic und seinen Urhebern Die Nutzung wird für Abrechnung und Compliance nachverfolgt Technische Kontrollen implementieren, um Folgendes zu verhindern: Downloads per Rechtsklick (soweit möglich) Direkten URL-Zugriff auf die Originaldateien Browser-Erweiterungen, die Downloads ermöglichen Nutzungsprotokolle führen für: Abrechnungsprüfung Compliance-Audits Beilegung von Streitfällen Beispiele für zulässige Integrationen ✅ Pfarr-Gemeindeblatt-Builder Pfarreien erstellen digitale Gemeindeblätter mit katholischen Bildern Der Inhalt wird auf der Website und in E-Mail-Newslettern angezeigt Es wird keine Download-Funktion bereitgestellt Die Abrechnung erfasst die Nutzung pro Pfarrei und pro Bild ✅ E-Mail-Plattform für Seelsorgebereiche Religiöse Organisationen gestalten E-Mail-Kampagnen Bilder werden direkt in E-Mails über API-URLs bereitgestellt Abrechnung pro versendeter E-Mail mit Inhalt Keine Dateispeicherung auf den Endgeräten der Nutzer ✅ Katholische CMS-Plattform Website-Builder mit integrierter Cathopic-Bibliothek Nutzer können in der Bibliothek stöbern und Bilder für ihre Seiten auswählen Inhalte werden über über die API bereitgestellte URLs eingebettet Abrechnung pro Tag der Nutzung pro Nutzer Beispiele für verbotene Integrationen ❌ KI-gestellter Bildgenerator Verwendung von Cathopic-Inhalten zum Trainieren von KI-Modellen Erstellen von Datensätzen für maschinelles Lernen Generieren ähnlicher Bilder auf Grundlage unserer Inhalte ❌ Druck-Design-Tool Ermöglichen, dass Nutzer druckbare Poster erstellen Bereitstellen eines Downloads für hochauflösendes Drucken Erstellen von PDFs mit Cathopic-Inhalten für den Druck ❌ Stockfoto-Marktplatz Cathopic-Inhalte als eigenständige Produkte weiterverkaufen Erstellen abgeleiteter Stockfoto-Sammlungen Weiterverbreitung von Inhalten an mehrere Kunden Bevor Sie mit dem Erstellen beginnen Wesentliche Lektüre: Lesen Sie die vollständige API-Lizenzvereinbarung Studieren Sie die technische Dokumentation unter api.cathopic.com/docs Verstehen Sie das Abrechnungsmodell im Detail (siehe Wie wird die API-Nutzung abgerechnet?) Planen Sie Ihre Integration so, dass alle Einschränkungen eingehalten werden Kontaktieren Sie uns über support, wenn Sie Fragen haben Merken Sie sich: Durch den Zugriff auf die API oder die Nutzung der API akzeptieren Sie alle Bedingungen in der API-Lizenzvereinbarung. Eine Nichteinhaltung kann zu einer sofortigen Beendigung und zu rechtlichen Konsequenzen führen.

Question 3

Welche sind die Rate Limits?

Accepted Answer

Derzeit setzen wir keine strikten Limits für Anfragen pro Sekunde durch. Allerdings wird ein fairer Umgang erwartet, um die Servicequalität für alle aufrechtzuerhalten. Aktueller Ansatz Statt harter Limits empfehlen wir einen verantwortungsvollen Einsatz: Streuen Sie Ihre Anfragen sinnvoll über die Zeit Verwenden Sie exponentielles Backoff, wenn Fehler auftreten Cachen Sie Antworten, um redundante Aufrufe zu vermeiden Kontaktieren Sie uns, wenn Sie mit hohem Traffic rechnen Best Practices Stark cachen: Speichern Sie Suchergebnisse für gängige Abfragen Halten Sie Mediendaten lokal vor, nachdem sie abgerufen wurden Rufen Sie /confirm nicht mehrfach für denselben Benutzer/dieselbe Ressource auf Operationen bündeln: Fassen Sie zusammengehörige Anfragen in Gruppen Fügen Sie kleine Verzögerungen zwischen den Batches hinzu Begrenzen Sie parallele Verbindungen (10–20 ist angemessen) Fehler sorgfältig behandeln: Implementieren Sie Retry-Logik mit exponentiellem Backoff Versuchen Sie bei Fehlschlägen nicht sofort erneut Protokollieren Sie Fehler zur Überwachung Erwartete Antwortzeiten /resources search: typischerweise 200–500 ms /resource details: unter 100 ms /confirm licensing: 300–800 ms Setzen Sie die Timeout-Zeit Ihres Clients auf mindestens 30 Sekunden, um gelegentlich langsamere Antworten zu berücksichtigen. Wenn Sie Limits erreichen Sie erhalten einen 429 Too Many Requests-Fehler. Wenn das passiert: // Implement exponential backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } return response; } catch (error) { if (i === maxRetries - 1) throw error; } } } Überwachen Sie Ihre Nutzung Verfolgen Sie die API-Aktivität in Einstellungen → API: Sehen Sie die insgesamt gemachten Anfragen Prüfen Sie aktive Lizenzen Bewerten Sie Nutzungstrends Beobachten Sie ungewöhnliche Muster Benötigen Sie höhere Limits? Wenn Ihr legitimer Anwendungsfall hohe Anfragevolumen erfordert (>1 Mio. Anfragen/Monat), kontaktieren Sie unser Team, um Folgendes zu besprechen: Ihre Anwendung und Ihre Traffic-Muster Das erwartete Anfragevolumen Garantierte Rate Limits, falls erforderlich

Question 4

Wie wird die API-Nutzung abgerechnet?

Accepted Answer

Die Cathopic-API verwendet ein Abrechnungsmodell „Pay-as-you-go“ auf Basis der tatsächlichen Inhaltsnutzung durch Ihre Endnutzer. Alle Abrechnungsbedingungen werden durch unsere API-Lizenzvereinbarung geregelt. Zwei Abrechnungsmodelle Die Abrechnung hängt davon ab, wie Ihre Endnutzer den Inhalt nutzen: 1. Website-Nutzung (Days-of-Use-Modell) Gilt, wenn Inhalte auf Websites, Blogs oder Webanwendungen angezeigt werden Berechnet pro Kalender-Tag, an dem ein Endnutzer auf einen bestimmten Inhalt zugreift Formel: Gesamttage der Nutzung × (ausgehandelter monatlicher Satz ÷ 30) Tagesgenaue Abrechnung stellt sicher, dass Sie nur für die tatsächliche Nutzung zahlen Wird separat pro Endnutzer und pro Inhaltselement erfasst 2. E-Mail-Nutzung (Pro-E-Mail-Modell) Gilt, wenn Inhalte in E-Mail-Nachrichten eingebunden werden Abgerechnet wird pro versendeter E-Mail-Nachricht (nicht pro Empfänger) Einmalige Abrechnung pro E-Mail, die den Inhalt enthält Satz wird bei der Einrichtung des API-Zugriffs ausgehandelt Wie die Abrechnung beginnt und endet Wasserzeichen-Inhalte sind kostenlos Der Inhalt wird zunächst mit einem Wasserzeichen angezeigt Die Vorschau mit Wasserzeichen erzeugt keine Kosten Ideal, um Endnutzern das Stöbern zu ermöglichen, bevor sie sich festlegen Kann für Tests und Testläufe verwendet werden Die Abrechnung beginnt, wenn das Wasserzeichen entfernt wird Der Endnutzer entscheidet sich, den Inhalt ohne Wasserzeichen zu verwenden Ihre Anwendung ruft POST /confirm auf mit: media_id: Der Inhaltbezeichner usage_type: Entweder „website“ oder „email“ client_identifier: Die eindeutige ID Ihres Endnutzers Die API gibt permanente URLs für Inhalte ohne Wasserzeichen zurück Die Abrechnung beginnt unmittelbar ab diesem Zeitpunkt Sie müssen diese URLs und Nutzungsdaten für die Abrechnungsverfolgung speichern Die Abrechnung endet, wenn der Inhalt entfernt wird Der Endnutzer entfernt den Inhalt oder hört auf, ihn zu verwenden Ihre Anwendung ruft POST /remove auf mit: media_id: Der Inhaltbezeichner client_identifier: Die ID des Endnutzers Die Abrechnung für diese konkrete Nutzung endet Sie müssen die URLs ohne Wasserzeichen aus Ihrer Datenbank löschen Beispiel für die Website-Abrechnung Nehmen wir an, Sie haben einen monatlichen Satz von für eine unbegrenzte Nutzung von Inhalten ausgehandelt: Szenario: Pfarrei A zeigt Bild Nr. 12345 auf ihrer Startseite an Tag 1: Sie rufen /confirm auf → Die Abrechnung beginnt Tage 1–15: Das Bild bleibt auf der Startseite (15 Tage der Nutzung) Tag 16: Die Pfarrei entfernt das Bild, Sie rufen /remove auf → Die Abrechnung endet Berechnung: 15 Tage × ( ÷ 30 Tage) = Abgerechnet: für diese konkrete Nutzung Wenn Pfarrei B dasselbe Bild auch für 10 Tage nutzt, wird das separat erfasst und kommt hinzu. Beispiel für die E-Mail-Abrechnung Nehmen wir an, Sie haben einen Satz von --.05 pro E-Mail ausgehandelt: Szenario: Ein Dienst sendet einen Newsletter mit Bild Nr. 67890 Aktion: Sie rufen /confirm auf mit usage_type: "email" Ergebnis: Einmalige Gebühr von --.05 für diese E-Mail Empfänger: Unabhängig davon, ob die E-Mail an 100 oder 10.000 Personen gesendet wird Abgerechnet: --.05 gesamt (nicht pro Empfänger) Monatliche Abrechnungslimits Ihre Vereinbarung kann monatliche Abrechnungslimits enthalten: Schützt Sie vor unerwartet hohen Rechnungen Wenn das Limit erreicht ist, kann zusätzliche Nutzung kostenlos sein oder zu einem reduzierten Satz erfolgen Der konkrete Limitbetrag wird bei der Einrichtung des API-Zugriffs ausgehandelt Gilt für die gesamten monatlichen Gebühren über alle Endnutzer hinweg Rechnungsstellung und Zahlung Rechnungsplan Rechnungen werden monatlich innerhalb der ersten 10 Tage eines jeden Monats ausgestellt Deckt die gesamte Nutzung des vorherigen Monats ab Detaillierte Aufschlüsselung der Nutzung nach Endnutzer und Inhaltselement Wird an die E-Mail-Adresse gesendet, die Ihrem API-Konto zugeordnet ist Zahlungsabwicklung Zahlungen werden ausschließlich über Stripe verarbeitet Automatische Belastung Ihrer registrierten Zahlungsmethode Sie müssen jederzeit gültige Zahlungsinformationen vorhalten Belege werden automatisch nach erfolgreicher Zahlung bereitgestellt Zahlungsfehler Wenn die Zahlung fehlschlägt, unternimmt das System 4 erneute Versuche Sie erhalten E-Mail-Benachrichtigungen über Zahlungsprobleme Wenn alle erneuten Versuche fehlschlagen, wird der API-Zugriff ausgesetzt Der Zugriff wird unmittelbar nach erfolgreicher Zahlung wiederhergestellt Unbezahlte Rechnungen können Zinskosten verursachen Ihre Pflichten zur Nachverfolgung Sie müssen genaue Aufzeichnungen führen über: Nutzungsprotokolle: Wann Inhalte bestätigt und entfernt wurden Endnutzer-IDs: Welche Nutzer auf welchen Inhalt zugegriffen haben Inhalts-IDs: Welche Medienobjekte verwendet wurden Nutzungstypen: Website vs. E-Mail für jede Nutzung Datumsangaben: Start- und Enddaten für die Website-Nutzung URLs: Gespeicherte URLs ohne Wasserzeichen für aktive Nutzung Diese Protokolle sind wichtig für: Die Überprüfung monatlicher Rechnungen Die Klärung von Abrechnungsstreitigkeiten Compliance-Audits durch Cathopic Ihre eigenen internen Auswertungen Zugriff auf Nutzungsberichte Sie können Ihre API-Nutzung in Echtzeit verfolgen: Gehen Sie zu Einstellungen → API Rufen Sie den Abschnitt „On-demand usage“ auf Sehen Sie Statistiken für den aktuellen Abrechnungszeitraum: Bisher aufgelaufene Gesamtkosten Anzahl der Website-Nutzungen Anzahl der E-Mail-Nutzungen Klicken Sie auf „View detailed report“ für die Aufschlüsselung nach: Endnutzer (client identifier) Inhaltselement Nutzungstyp Datumsbereich Einzelkosten Exportieren Sie Berichte als CSV für Ihre Unterlagen Sätze aushandeln Die API-Preise werden für jeden Kunden individuell festgelegt: Die Sätze werden im Rahmen des Prozesses zur Anforderung des API-Zugriffs ausgehandelt Basierend auf Ihrem erwarteten Nutzungsvolumen Basierend auf Ihrem konkreten Anwendungsfall und Integrationstyp Kann Mengenrabatte für Anwendungen mit hoher Nutzung enthalten Abrechnungslimits können ausgehandelt werden, um kalkulierbare Kosten zu ermöglichen Um die Preise zu besprechen: Besuchen Sie unsere Support-Seite Wählen Sie „API access request“ Beschreiben Sie Ihre Integration und die erwartete Nutzung Unser Team erstellt ein individuelles Angebot Das vollständige Lizenzwerk verstehen Die Abrechnung ist nur ein Aspekt der API-Vereinbarung. Prüfen Sie die vollständigen Bedingungen: Lesen Sie die vollständige API-Lizenzvereinbarung Verstehen Sie die Nutzungsbeschränkungen (nur digital, keine KI/ML, keine Downloads) Kennt Ihre Pflichten zur Nachverfolgung und Berichterstattung Prüfen Sie Klauseln zu geistigem Eigentum und zur Beendigung Für technische Details zur Implementierung: Sehen Sie sich die Endpunkte /confirm und /remove an unter api.cathopic.com/docs Verstehen Sie, wie Sie die Nutzung für Ihre konkrete Integration berechnen Prüfen Sie bewährte Verfahren für eine genaue Abrechnungsnachverfolgung Merken Sie sich: Die genaue Nachverfolgung der Nutzung liegt in Ihrer Verantwortung. Führen Sie detaillierte Protokolle, um eine korrekte Abrechnung und die Einhaltung der Lizenzvereinbarung sicherzustellen.

Question 5

So beantragst du Entwicklerzugriff für die API und OAuth

Accepted Answer

Cathopic prüft ein Entwicklerkonto einmal. Diese einzelne Freigabe schaltet sowohl die kommerzielle API als auch das OAuth-Anwendungsmanagement frei; du stellst keine separaten Anfragen. Nach der Freigabe erstellst und verwaltest du deine API-Schlüssel und OAuth-Zugangsdaten in den Cathopic-Einstellungen. Entwickler benötigen niemals einen Cathopic-Serverbefehl oder Zugriff auf die Infrastruktur. 1. Bereite dein Cathopic-Konto vor Erstelle ein Cathopic-Konto, verifiziere die E-Mail-Adresse und stelle sicher, dass der Benutzername und die E-Mail in der Anfrage genau zu diesem Konto passen. 2. Sende die Entwickleranfrage Öffne das Cathopic-Kontaktformular. Wähle Entwicklerzugriff anfordern. Bestätige den Cathopic-Benutzernamen und beschreibe das Produkt, die Organisation und die beabsichtigte Nutzung des Katalogs. Sende das Formular. Die Anfrage erscheint im internen Prüf-Dashboard von Cathopic. 3. Erhalte die Entscheidung Cathopic prüft das Konto und den Anwendungsfall. Bei Freigabe erhält der Entwickler eine E-Mail mit den nächsten Schritten und einem Link zu Einstellungen → Developer / API → OAuth applications. Falls weitere Informationen benötigt werden, kontaktiert Cathopic die E-Mail aus der Anfrage. 4. Erstelle die Anwendung Wähle eine vertrauliche Webanwendung, wenn das Produkt über einen sicheren Backend-Server verfügt, oder eine öffentliche PKCE-Anwendung für Clients nur im Browser, für mobile oder Desktop-Anwendungen. Gib den öffentlichen Namen, die Beschreibung, die Website, die Datenschutzrichtlinie, den Security-Kontakt, die exakten Callback-URLs und nur die benötigten Scopes an. 5. Speichere die Zugangsdaten Die Client-ID identifiziert die Integration und wird von allen Nutzern dieses Produkts geteilt. Benutzerautorisierung und Tokens bleiben für jedes Cathopic-Konto getrennt. Ein vertrauliches Client-Secret wird nur einmal angezeigt und muss auf dem Server der Anwendung verschlüsselt werden. Füge es niemals in Browser-Code, generierte Websites, Logs, Support-Nachrichten oder ein öffentliches Repository ein. Auf derselben Seite kann der freigegebene Entwickler Callbacks und Scopes bearbeiten, ein vertrauliches Secret rotieren oder die Anwendung widerrufen.

Question 6

Wie funktionieren API-Schlüssel?

Accepted Answer

API-Schlüssel sind Ihre Authentifizierungsdaten, um auf die Cathopic-API zuzugreifen. Zu verstehen, wie sie funktionieren, ist entscheidend für eine sichere und effektive API-Integration. Was ist ein API-Schlüssel? Ein API-Schlüssel ist ein eindeutiges, geheimes Token, das Ihre Anwendung identifiziert und sie zur Nutzung der Cathopic-API berechtigt: Eine lange alphanumerische Zeichenkette (z. B. sk_live_abc123xyz789...) Funktioniert sowohl als Authentifizierung als auch als Autorisierung Ist mit Ihrem Cathopic-Konto und Ihrer Abrechnung verknüpft Kann aktiv oder inaktiv sein Lebenszyklus des Schlüssels Erstellung: Erstellen Sie Schlüssel in Einstellungen → API Geben Sie jedem Schlüssel einen aussagekräftigen Namen ("Production Website", "Staging", "Mobile App") Kopieren Sie den vollständigen Schlüssel sofort – er wird nur einmal angezeigt Speichern Sie ihn sicher (Umgebungsvariablen, Secrets-Manager, Passwort-Manager) Verwendung: Fügen Sie ihn in den x-api-key-HTTP-Header bei jeder Anfrage ein Schlüssel werden bei jeder Anfrage serverseitig validiert Alle API-Nutzung wird erfasst und Ihrem Konto in Rechnung gestellt Deaktivierung: Schlüssel können vorübergehend deaktiviert werden, ohne gelöscht zu werden Nützlich für die Fehlersuche oder um eine bestimmte Integration zu pausieren Kann jederzeit wieder aktiviert werden Löschung: Entfernt den Schlüssel dauerhaft Kann nicht rückgängig gemacht oder wiederhergestellt werden Alle Anfragen mit diesem Schlüssel schlagen sofort fehl Richtlinien zur Verwaltung von Schlüsseln Sicherheit: Schlüssel niemals in die Versionsverwaltung einchecken: Verwenden Sie .env-Dateien und fügen Sie sie zu .gitignore hinzu Niemals in Client-seitigem Code offenlegen: API-Schlüssel sollten nur serverseitig verwendet werden Umgebungsvariablen verwenden: Speichern Sie Schlüssel in process.env.CATHOPIC_API_KEY oder einer entsprechenden Variable Regelmäßig rotieren: Ändern Sie Schlüssel in regelmäßigen Abständen (quartalsweise oder nach Änderungen im Team) Separate Schlüssel pro Umgebung verwenden: Verwenden Sie unterschiedliche Schlüssel für Entwicklung, Staging und Produktion Organisation: Aussagekräftige Namen: Benennen Sie Schlüssel nach Zweck: "Production Website", "iOS App", "Email System" Dokumentieren der Zuständigkeit: Verfolgen Sie, welches Teammitglied jeden Schlüssel erstellt hat Regelmäßige Audits: Überprüfen Sie aktive Schlüssel monatlich und entfernen Sie nicht verwendete Mehrere API-Schlüssel Sie können mehrere API-Schlüssel für unterschiedliche Zwecke erstellen: Pro Umgebung: Separate Schlüssel für Entwicklung, Staging und Produktion Pro Anwendung: Unterschiedliche Schlüssel für Website, Mobile App, interne Tools Pro Teammitglied: Individuelle Schlüssel für Entwickler (einfacher zu verfolgen und zu widerrufen) Alle Schlüssel unter Ihrem Konto teilen sich dieselbe Abrechnung. Die Nutzung aus allen Schlüsseln wird in Ihrer monatlichen Rechnung zusammengefasst. Nutzung von Schlüsseln überwachen Beobachten Sie die Aktivität für jeden Schlüssel: Gehen Sie zu Einstellungen → API Sehen Sie sich die Liste aller Schlüssel mit den letzten Verwendungsdaten an Klicken Sie auf einen Schlüssel, um detaillierte Nutzungsstatistiken zu sehen Überwachen Sie unerwartete Aktivitäten Was tun, wenn ein Schlüssel kompromittiert wurde? Wenn Sie glauben, dass ein API-Schlüssel offengelegt wurde: Löschen oder deaktivieren Sie den Schlüssel sofort in Einstellungen → API Erstellen Sie einen neuen Ersatzschlüssel Aktualisieren Sie Ihre Anwendung mit dem neuen Schlüssel Prüfen Sie die Nutzungsprotokolle auf verdächtige Aktivitäten Kontaktieren Sie den Support, wenn Sie eine nicht autorisierte Nutzung feststellen Beispiel: Schlüssel sicher speichern Node.js mit Umgebungsvariablen: // .env-Datei (zu .gitignore hinzufügen!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Ihr Code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }) }); Python mit Umgebungsvariablen: import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'} )

Question 7

Wie authentifiziere ich Anfragen?

Accepted Answer

Alle Anfragen an die Cathopic-API müssen mit Ihrem API-Schlüssel authentifiziert werden. So authentifizieren Sie Ihre API-Aufrufe richtig. Authentifizierungsmethode Die Cathopic-API verwendet API-Schlüssel-Authentifizierung über HTTP-Header: Header-Name: x-api-key Header-Wert: Ihr vollständiger API-Schlüssel Erforderlich für: Alle API-Endpunkte Groß-/Kleinschreibung beachten: Header-Namen und Werte müssen exakt übereinstimmen Beispiel für grundlegende Authentifizierung cURL: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Virgin Mary", "page": 1, "page_size": 20, "order": "popular" }' JavaScript (fetch): const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': process.env.CATHOPIC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }) }); const data = await response.json(); console.log(data); JavaScript (axios): const axios = require('axios'); const response = await axios.post( 'https://api.cathopic.com/resources', { query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }, { headers: { 'x-api-key': process.env.CATHOPIC_API_KEY } } ); console.log(response.data); Python (requests): import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={ 'x-api-key': api_key, 'Content-Type': 'application/json' }, json={ 'query': 'Virgin Mary', 'page': 1, 'page_size': 20, 'order': 'popular' } ) data = response.json() print(data) PHP (cURL):

Question 8

Wie rotiere ich einen API-Schlüssel?

Accepted Answer

Das regelmäßige Rotieren von API-Schlüsseln ist eine wichtige Sicherheitsmaßnahme. So können Sie Ihre Schlüssel sicher rotieren, ohne Ihren Dienst zu unterbrechen. Warum API-Schlüssel rotieren? Sicherheits-Best-Practice: Begrenzt die Gefährdung, falls ein Schlüssel jemals kompromittiert wurde Wechsel im Team: Wenn Entwickler das Unternehmen verlassen oder Rollen wechseln Verdacht auf Kompromittierung: Wenn Sie glauben, dass ein Schlüssel möglicherweise offengelegt wurde Compliance: Einige Sicherheitsrichtlinien verlangen eine regelmäßige Rotation von Schlüsseln Änderungen in der Umgebung: Wenn Sie Infrastruktur migrieren oder refactoring durchführen Standard-Rotationsprozess (ohne Ausfallzeit) Schritt 1: Erstellen Sie einen neuen Schlüssel Melden Sie sich bei Einstellungen → API an Klicken Sie auf "Neuen API-Schlüssel erstellen" Benennen Sie ihn aussagekräftig (z. B. "Production Web v2") Kopieren Sie den neuen Schlüssel sofort – er wird nur einmal angezeigt Speichern Sie ihn sicher Schritt 2: Aktualisieren Sie Ihre Anwendung Stellen Sie den neuen Schlüssel in Ihrer Anwendung bereit (Umgebungsvariablen, Secrets-Manager usw.) Starten Sie Ihre Anwendung neu, um den neuen Schlüssel zu laden Prüfen Sie, ob der neue Schlüssel korrekt funktioniert Beobachten Sie auf mögliche Fehler Schritt 3: Überwachen Sie die Umstellung Behalten Sie beide Schlüssel vorübergehend aktiv Prüfen Sie Einstellungen → API, um die Angaben zu "Last used" (zuletzt verwendet) zu sehen Warten Sie, bis der alte Schlüssel keine aktuelle Aktivität mehr anzeigt Stellen Sie sicher, dass alle Instanzen/Dienste auf den neuen Schlüssel umgestellt haben Schritt 4: Löschen Sie den alten Schlüssel Sobald bestätigt ist, dass der alte Schlüssel nicht mehr verwendet wird Löschen oder deaktivieren Sie den alten Schlüssel in Einstellungen → API Dokumentieren Sie die Rotation für Ihre Unterlagen Schneller Rotationsprozess (falls kompromittiert) Wenn ein Schlüssel eindeutig kompromittiert ist und Sie sofort handeln müssen: Löschen Sie zuerst den kompromittierten Schlüssel in Einstellungen → API Erstellen Sie einen neuen Ersatzschlüssel Stellen Sie den neuen Schlüssel schnell in allen Anwendungen bereit Nehmen Sie eine kurze Ausfallzeit in Kauf, um unbefugten Zugriff zu verhindern Überwachen Sie die Nutzungsprotokolle auf verdächtige Aktivitäten Kontaktieren Sie bei Bedarf den Support Strategie für die Rotation in mehreren Umgebungen Für Produktionssysteme verwenden Sie einen gestaffelten Ansatz: Woche 1: Entwicklung Erstellen und stellen Sie den neuen Schlüssel in der Dev-Umgebung bereit Gründlich testen Woche 2: Staging Stellen Sie den neuen Schlüssel im Staging bereit Führen Sie Integrationstests durch Beobachten Sie auf Probleme Woche 3: Produktion Stellen Sie den neuen Schlüssel in der Produktion während einer Phase mit geringem Traffic bereit Genau überwachen Behalten Sie den alten Schlüssel 24–48 Stunden als Fallback aktiv Woche 4: Aufräumen Prüfen Sie, dass der alte Schlüssel keine Aktivität mehr anzeigt Löschen Sie den alten Schlüssel Aktualisieren Sie die Dokumentation Beispiel für Automatisierung Skript, um zu helfen zu überprüfen, ob die Schlüsselrotation abgeschlossen ist: #!/bin/bash # check-api-key.sh OLD_KEY="sk_live_OLD123..." NEW_KEY="sk_live_NEW789..." echo "Testing old key..." OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $OLD_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Testing new key..." NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $NEW_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Old key status: ${OLD_RESPONSE: -3}" echo "New key status: ${NEW_RESPONSE: -3}" if [ "${NEW_RESPONSE: -3}" == "200" ]; then echo "✅ New key is working!" else echo "❌ New key failed!" fi Best Practices Regelmäßig rotieren: Alle 90 Tage für Produktionsschlüssel Rotationen dokumentieren: Führen Sie ein Protokoll darüber, wann Schlüssel rotiert wurden und warum Vor dem Löschen testen: Verifizieren Sie immer, dass der neue Schlüssel funktioniert, bevor Sie den alten entfernen Mehrere Schlüssel verwenden: Schlüssel pro Umgebung trennen, damit die Rotation einfacher wird Wo möglich automatisieren: Nutzen Sie Secrets-Management-Tools, die eine automatische Rotation unterstützen Checkliste nach der Rotation Bestätigen Sie diese Punkte nach der Rotation: ✅ Alle Produktionsinstanzen verwenden den neuen Schlüssel ✅ Alle Staging-/Dev-Umgebungen aktualisiert (falls derselbe Schlüssel verwendet wird) ✅ Umgebungsvariablen aktualisiert ✅ CI/CD-Secrets aktualisiert ✅ Dokumentation aktualisiert ✅ Teammitglieder informiert ✅ Alter Schlüssel gelöscht ✅ Rotation für Audit-Zwecke protokolliert

Question 9

Wie sichere ich meine Zugangsdaten?

Accepted Answer

Ihre API-Schlüssel sind der Zugang zu Ihrem Cathopic-Konto. Wenn Sie sie sicher aufbewahren, verhindern Sie unbefugten Zugriff und schützen vor Abrechnungsbetrug. Die goldene Regel: Schlüssel geheim halten Behandeln Sie Ihre API-Schlüssel wie Passwörter. Häufige Fehler, die Sie vermeiden sollten: Schlüssel direkt im Quellcode fest einbauen Schlüssel in Git oder anderem Versionskontrollsystem ablegen Schlüssel in clientseitigem JavaScript oder in mobilen Apps verwenden Schlüssel per E-Mail, Slack oder Messenger-Apps teilen Schlüssel an öffentlichen Orten speichern (öffentliche Repositories, Wikis usw.) Umgebungsvariablen verwenden Speichern Sie Schlüssel in Umgebungsvariablen statt im Code: // .env-Datei (zu .gitignore hinzufügen!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Ihr Code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; So trennen Sie sensible Daten von Ihrer Codebasis und erleichtern das Rotieren der Schlüssel. Nur serverseitig API-Aufrufe müssen von Ihren Backend-Servern ausgeführt werden, nicht von Browsern oder mobilen Apps. Wenn Nutzer Zugriff auf Cathopic-Ressourcen benötigen: Erstellen Sie einen Backend-Endpunkt, der Ihren API-Schlüssel verwendet Ihr Frontend ruft IHREN Endpunkt auf, nicht direkt Cathopic Ihr Server validiert die Nutzeranfrage, bevor er Cathopic aufruft Nach IP einschränken (falls möglich) Manche Infrastrukturen erlauben IP-Whitelisting. Wenn Ihre API-Aufrufe von bekannten IPs kommen: Konfigurieren Sie Firewall-Regeln, um den ausgehenden Zugriff zu begrenzen Verwenden Sie dedizierte Service-Accounts mit minimalen Berechtigungen Überwachen Sie Zugriffsprotokolle auf ungewöhnliche Aktivitäten Wenn ein Schlüssel kompromittiert wurde Wenn Sie vermuten, dass ein Schlüssel offengelegt wurde: Erzeugen Sie sofort einen neuen API-Schlüssel Aktualisieren Sie Ihre Anwendung mit dem neuen Schlüssel Löschen Sie den kompromittierten Schlüssel Prüfen Sie die Nutzungsprotokolle auf verdächtige Aktivitäten Kontaktieren Sie den Support, wenn Sie unbefugte Abrechnungen sehen Verwalten Sie Ihre Schlüssel sicher unter Einstellungen → API.

Question 10

Häufige Authentifizierungsfehler

Accepted Answer

Wenn du Probleme hast, dich mit der Cathopic-API zu authentifizieren, findest du hier die häufigsten Fehler und wie du sie behebst. 401 Unauthorized Der häufigste Authentifizierungsfehler: HTTP 401 Unauthorized { "message": "Unauthorized" } Häufige Ursachen: Fehlender x-api-key-Header Ungültiger oder abgelaufener API-Schlüssel Tippfehler im API-Schlüssel Leerzeichen vor/nach dem Schlüssel Schlüssel nicht aus der Umgebungsvariable geladen So behebst du es: Prüfe, ob der Header-Name exakt x-api-key ist (klein geschrieben) Kopiere deinen API-Schlüssel erneut aus Einstellungen → API Prüfe, ob Umgebungsvariablen geladen werden: console.log(process.env.CATHOPIC_API_KEY) Leerzeichen entfernen: apiKey.trim() Überprüfe, ob der Schlüssel aktiv ist (nicht gelöscht oder deaktiviert) Falscher Header-Name Die API benötigt x-api-key, nicht andere gängige Header-Namen: // ❌ FALSCH Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ RICHTIG x-api-key: sk_live_abc... Fehler beim Unauthorized Token HTTP 401 Unauthorized { "error": "Unauthorized token" } Ursache: Dein API-Schlüssel wurde deaktiviert oder gelöscht. So behebst du es: Prüfe, ob der Schlüssel noch aktiv ist in Einstellungen → API Aktiviere den Schlüssel erneut, falls er deaktiviert wurde Erstelle einen neuen Schlüssel, falls der alte gelöscht wurde Umgebungsvariable nicht geladen Dein Code findet den API-Schlüssel nicht: // Gibt undefined zurück const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined So behebst du es: Node.js: // Stelle sicher, dass .env geladen wird require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; if (!apiKey) { throw new Error('CATHOPIC_API_KEY not set'); } Python: import os from dotenv import load_dotenv load_dotenv() api_key = os.environ.get('CATHOPIC_API_KEY') if not api_key: raise ValueError('CATHOPIC_API_KEY not set') Fehler durch Offenlegung auf der Client-Seite Versuchst du, den API-Schlüssel in Browser-JavaScript zu verwenden: // ❌ Das wird fehlschlagen (Schlüssel funktionieren nicht im Browser) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); So behebst du es: Erstelle einen serverseitigen Endpunkt, der Anfragen an die Cathopic-API weiterleitet (proxy). Siehe „Wie sichere ich meine Zugangsdaten?“ für Beispiele. CORS-Fehler Wenn du CORS-Fehler in der Browser-Konsole siehst: Access to fetch has been blocked by CORS policy... Ursache: Du versuchst, die API direkt aus clientseitigem JavaScript aufzurufen. So behebst du es: Die Cathopic-API ist nur serverseitig verfügbar. Du musst Anfragen über dein eigenes Backend weiterleiten. Authentifizierung testen Schneller Test, um deine Einrichtung zu prüfen: curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Achte auf eine HTTP-200-Antwort # Wenn 401, prüfe den Schlüssel sorgfältig Debugging-Checkliste Wenn die Authentifizierung weiterhin fehlschlägt: ☐ Der Header-Name ist x-api-key (Groß-/Kleinschreibung beachten) ☐ Der API-Schlüssel ist der vollständige Schlüssel (beginnt mit sk_live_ oder ähnlich) ☐ Kein Bearer-Präfix oder Anführungszeichen um den Schlüssel ☐ Die Umgebungsvariable ist gesetzt und wird geladen ☐ Die Anfrage wird serverseitig gesendet, nicht vom Browser ☐ Der Schlüssel ist aktiv in Einstellungen → API ☐ Die Zahlungsmethode ist hinzugefügt und gültig Wenn die Probleme weiterhin bestehen, kontaktiere den Entwickler-Support mit: Die Fehlermeldung Die letzten 4 Ziffern deines API-Schlüssels Programmiersprache und Framework Beispielcode (ohne deinen vollständigen Schlüssel offenzulegen)

Question 11

Verfügbare Suchparameter

Accepted Answer

Der Endpunkt /resources akzeptiert mehrere Parameter, um Ihre Suchergebnisse zu verfeinern. Grundlegende Suche POST https://api.cathopic.com/resources { "query": "Saint Francis", "page": 1, "page_size": 20, "order": "popular" } Parameter query (string, optional) Ihr Suchbegriff. Lassen Sie ihn leer, um alle Ressourcen zu erhalten. Beispiele: "Virgin Mary", "Eucharist", "cross" Unterstützt unscharfes Matching und Tippfehler-Toleranz Durchsucht Titel, Beschreibungen und Tags page (integer, default: 1) Welche Seite der Ergebnisse zurückgegeben werden soll. Beginnt bei 1. page_size (integer, default: 20, max: 100) Anzahl der Ergebnisse pro Seite. Das Maximum ist 100, um die Performance zu erhalten. order (string, default: "popular") So werden die Ergebnisse sortiert: popular - Zuerst die meist heruntergeladenen Ressourcen recent - Zuerst die neuesten Uploads Antwortstruktur { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Resource title", "description": "Resource description", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Praktische Beispiele Die ersten 10 meistbeliebten Ressourcen zum Thema Gebet abrufen: { "query": "prayer", "page": 1, "page_size": 10, "order": "popular" } Neueste Uploads abrufen, ohne bestimmten Suchbegriff: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Seite 3 mit Heiligenbildern durchsuchen: { "query": "saints", "page": 3, "page_size": 20, "order": "popular" } Für die vollständige API-Referenz besuchen Sie api.cathopic.com/docs.

Question 12

Wie lade ich Bilder über die API herunter?

Accepted Answer

Wichtige Klarstellung: Die API ermöglicht kein „Herunterladen“ im herkömmlichen Sinne. Stattdessen stellt sie dauerhafte URLs zu weboptimierten Inhalten bereit, die Ihre Anwendung den Endnutzern bereitstellt. Dies wird durch unsere API-Lizenzvereinbarung geregelt. Sie laden keine Dateien herunter Die Cathopic API funktioniert grundsätzlich anders als herkömmliche Downloads: Keine Dateitransfers: Sie erhalten oder speichern niemals die eigentlichen Bild-/Videodateien Zugriff über URLs: Die API stellt URLs bereit, die auf von Cathopic gehostete Inhalte zeigen Nur weboptimiert: Inhalte werden in einer für die digitale Anzeige geeigneten Auflösung bereitgestellt Keine Originaldateien: Hochauflösende Originale sind über die API niemals zugänglich Immer gehostet: Inhalte bleiben auf den Cathopic-Servern oder einem autorisierten CDN Verfügbare Auflösungen Die API stellt drei weboptimierte Größen bereit: Klein: Geeignet für Thumbnails und kleine Einbettungen (typischerweise ~400 px breit) Mittel: Gut für Standard-Webinhalte (typischerweise ~800 px breit) Groß: Beste Qualität für die Webanzeige (typischerweise ~1200 px breit) Wichtige Einschränkungen: Hochauflösende Originaldateien werden NIEMALS bereitgestellt Auflösungen sind für die Bildschirmanzeige optimiert, nicht für den Druck Dateigrößen werden für eine schnelle Webbereitstellung komprimiert Sie können keine benutzerdefinierten Auflösungen oder Originalqualität anfordern Für die vollständigen Bedingungen lesen Sie die vollständige API-Lizenzvereinbarung und sehen Sie sich die technische Dokumentation an unter api.cathopic.com/docs. Das „Herunterladen“ von Bildern umfasst zwei Schritte: die Lizenzierung der Ressource mit /confirm und anschließend die Verwendung der zurückgegebenen URLs. Schritt 1: Lizenzieren Sie die Ressource Rufen Sie /confirm auf, um eine Ressource für einen bestimmten Endnutzer zu lizenzieren: POST https://api.cathopic.com/confirm x-api-key: IHR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parameter: media_id - Die Ressourcen-ID aus Ihren Suchergebnissen usage_type - Entweder „website“ oder „email“ client_identifier - Eindeutige ID für Ihren Endnutzer Schritt 2: Verwenden Sie die Download-URLs Die Antwort enthält dauerhafte URLs in mehreren Formaten: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Wichtig: URLs speichern Die zurückgegebenen URLs sind dauerhaft – speichern Sie sie in Ihrer Datenbank: // Nach dem Aufruf von /confirm const response = await api.confirm(mediaId, userId); // In der Datenbank speichern await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Beim nächsten Mal aus der DB abrufen, statt /confirm erneut aufzurufen Das richtige Format wählen AVIF-Format: Kleinere Dateigrößen (bessere Performance) Bessere Komprimierung Empfohlen für moderne Browser Nicht in älteren Browsern unterstützt JPEG-Format: Universelle Kompatibilität Größere Dateigrößen Als Fallback für ältere Browser verwenden Wichtige Erinnerung ⚠️ Prüfen Sie immer Ihre Datenbank, bevor Sie /confirm aufrufen. Wenn Sie es mehrfach für denselben Nutzer und dieselbe Ressource aufrufen, entstehen doppelte Gebühren. Vollständige Dokumentation unter api.cathopic.com/docs.

Question 13

Pagination und Sortierung handhaben

Accepted Answer

Die API gibt Suchergebnisse in Seiten zurück. So navigieren Sie effizient durch große Ergebnislisten. Grundlegende Pagination POST /resources { "query": "saints", "page": 1, "page_size": 20 } Antwort: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 items ... ] } Die Antwort zeigt Ihnen, dass es insgesamt 1.523 Ergebnisse gibt und Sie Seite 1 mit 20 Einträgen ansehen. Gesamtseiten berechnen const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 Seiten Nächste Seite laden // Einfache nächste Seite currentPage++; // Oder Pagination-UI aufbauen for (let page = 1; page <= totalPages; page++) { // Seiten-Schaltfläche erstellen } Seitengröße optimieren Wählen Sie die Seitengröße entsprechend Ihrem Anwendungsfall: Kleine Seiten (10-20 Einträge): Schnelleres anfängliches Laden Gut für nutzerseitige Suche Mehr API-Anfragen erforderlich Große Seiten (50-100 Einträge): Weniger API-Anfragen Gut für Stapelverarbeitung Langsamere einzelne Anfragen Maximum sind 100 Einträge Sortieroptionen Beliebt (Standard): { "order": "popular" } Gibt zuerst die am häufigsten heruntergeladenen Ressourcen zurück. Am besten, um qualitativ hochwertige, bewährte Inhalte anzuzeigen. Neueste: { "order": "recent" } Gibt zuerst die neuesten Uploads zurück. Gut, um frische Inhalte zu entdecken. Beispiel für unendliches Scrollen let currentPage = 1; const pageSize = 20; let isLoading = false; let hasMore = true; async function loadMore() { if (isLoading || !hasMore) return; isLoading = true; const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'prayer', page: currentPage, page_size: pageSize, order: 'popular' }) }); const data = await response.json(); // Ergebnisse zur UI hinzufügen appendResults(data.results); // Prüfen, ob es weitere Seiten gibt const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Beim Scrollen auslösen window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Tipps zur Performance Ergebnisse lokal cachen, um redundante Anfragen zu vermeiden Passende Seitengrößen für Ihren Anwendungsfall verwenden Ladezustände implementieren, um die Nutzererfahrung zu verbessern Bei sehr großen Listen Virtualisierung in Betracht ziehen Nicht alle Seiten auf einmal abrufen – bei Bedarf laden Weitere Details finden Sie in der vollständigen Dokumentation unter api.cathopic.com/docs.

Question 14

So durchsuchen Sie den Katalog und verwenden Cathopic-Vorschau-URLs

Accepted Answer

Verwenden Sie GET /api/v2/catalog mit catalog.read. Es nutzt Cathopics vorhandene fehlertolerante Fuzzy-Suchschicht und lädt dieselben kanonischen Medienmodelle, die auch im Website-Grid verwendet werden. Parameter q oder query: Text bis zu 250 Zeichen. type: photo, video, graphic, artwork, ai oder all. orientation: landscape, portrait, square oder all. sort: most_recent, popular oder popular_alltime. page, per_page : bis zu 50 und locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENVorschau-URLs unverändert verwenden Jedes Ergebnis enthält preview.url und preview.transformation_url_template. Sie stammen aus exakt demselben Grid-Presenter, CDN-Host, Speicherpfad und denselben Watermark-Regeln, die auf cathopic.com verwendet werden. Verwenden Sie sie unverändert, damit Integrationen die vorhandenen Cloudflare-Cache-Keys wiederverwenden. Laden Sie keine weitere Kopie hoch oder proxyn Sie sie nicht unnötig. Fügen Sie keine cache-busting Query-Parameter hinzu. Ersetzen Sie <OPTIONS> nur durch stabile Cloudflare-Bildoptionen. Vorschauen verbrauchen niemals einen Download. already_licensed umfasst individuelle und Entitlements für gemeinsam genutzte Teams.

Question 15

So lizenzieren und laden Sie eine Ressource sicher herunter

Accepted Answer

Die Erstellung der Lizenz und die Erstellung der Original-URL sind getrennt, sodass Wiederholungsversuche sicher sind und frische URLs nie erneut berechnet werden. 1. Lizenz erstellen POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Verwenden Sie einen eindeutigen Schlüssel aus 8 bis 160 druckbaren ASCII-Zeichen für den logischen Auswahlversuch und behalten Sie ihn beim erneuten Versuch bei. Eine neue Lizenz gibt 201 zurück; eine idempotente Wiederholung gibt 200 mit derselben Lizenz-ID zurück. Cathopic prüft zuerst das Original. In einer einzigen Transaktion sperrt es das einzelne oder Team-Abonnement, prüft den Medienzugriff und vorhandene geteilte Berechtigungen, verbraucht höchstens einen Download und zeichnet die Berechtigung, die Historie und die Lizenz auf. 2. Original-URL anfordern POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENDie URL läuft nach fünf Minuten ab. Fordern Sie für einen erneuten Download eine neue URL an; erstellen Sie keine weitere Lizenz. Cathopic leitet den Speicherpfad ab und akzeptiert niemals einen beliebigen Pfad. Wichtige Fehler subscription_required: kein aktiver bezahlter Zugriff. media_type_not_in_plan: Typ nicht enthalten. download_balance_exhausted: keine Downloads für den Tarif mit Kontingent mehr verfügbar. file_unavailable: Original fehlt; keine Berechnung. idempotency_key_conflict: Schlüssel wurde für eine andere Media-ID verwendet. Bewahren Sie die X-Request-Id für den Support auf, aber protokollieren Sie niemals Tokens, Secrets oder signierte URLs. Gehen Sie nach 429 oder vorübergehenden 5xx-Antworten mit Jitter zurück.

Question 16

OAuth 2.0-Schnellstart für Cathopic verbundene Apps

Accepted Answer

Cathopic Connected Apps verwenden OAuth 2.0 Authorization Code mit obligatorischem PKCE S256. Die gleiche Entwicklerfreigabe schaltet auch die kommerzielle API von Cathopic frei, aber OAuth-Verbindungen nutzen Benutzertokens und den Tarif des verbundenen Benutzers anstelle von API-Schlüsseln und nutzungsabhängiger API-Abrechnung. 1. Zugriff erhalten und die Anwendung registrieren Senden Sie die einzelne Entwicklerzugriffsanfrage über das Kontaktformular. Nachdem Cathopic das Konto per E-Mail genehmigt hat, öffnen Einstellungen → Entwickler / API → OAuth-Anwendungen, erstellen Sie die Anwendung, registrieren Sie ihre exakten Callbacks und erforderlichen Scopes und speichern Sie ihr einmaliges Geheimnis, falls sie vertraulich ist. 2. Den Autorisierungsserver ermitteln GET https://cathopic.com/.well-known/oauth-authorization-server3. Den Benutzer umleiten GET https://cathopic.com/oauth/authorize ?client_id=CLIENT_ID &redirect_uri=EXACT_CALLBACK &response_type=code &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read &state=UNGUESSABLE_STATE &code_challenge=BASE64URL_SHA256_VERIFIER &code_challenge_method=S256 &ui_locales=enErstellen Sie eine einzige URL; die Zeilenumbrüche dienen nur dazu, das Beispiel lesbar zu machen. Generieren Sie bei jedem Versuch neuen State mit hoher Entropie und neue PKCE-Werte. ui_locales ist optional und kann eine unterstützte Sprache anfordern, wie z. B. en oder es. Wenn eine Anmeldung erforderlich ist, setzt Cathopic die gleiche Autorisierungsanfrage fort und zeigt dann den Berechtigungsbildschirm an. 4. Den Callback validieren und den Code austauschen Vergleichen Sie den zurückgegebenen State, bevor Sie den Code austauschen. Die Redirect-URI muss bytegenau übereinstimmen. POST https://cathopic.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIERÖffentliche Anwendungen lassen client_secretweg. Speichern Sie Tokens und vertrauliche Geheimnisse nur auf dem Server und verschlüsseln Sie sie im Ruhezustand. Zugriffstokens sind 30 Minuten gültig; Refresh-Tokens sind bis zu 30 Tage gültig und werden bei Verwendung rotiert. Häufige Prüfungen Ein abgelehnter Callback unterscheidet sich in der Regel von der registrierten URI durch Schema, Host, Port, Pfad, Groß-/Kleinschreibung oder einen abschließenden Schrägstrich. invalid_request vor Zustimmung bedeutet, dass PKCE S256, die Challenge oder der State fehlt oder ungültig ist. invalid_grant bedeutet üblicherweise, dass ein Code oder ein rotierter Refresh-Token wiederverwendet wurde oder dass sich der Callback oder der Verifier geändert hat. Nach einem 401 einmal aktualisieren; wenn das Refresh fehlschlägt, bitten Sie den Benutzer, erneut zu verbinden. Ein 403 bedeutet, dass dem Token der erforderliche Scope fehlt. Siehe die vollständige OpenAPI-Übereinkunft und die detaillierte Anleitung zur Integration Connected Apps.

Question 17

Wie verbinde ich Cathopic mit einer anderen Anwendung?

Accepted Answer

Eine freigegebene Plattform ermöglicht es Ihnen, den Cathopic-Katalog zu nutzen, ohne Ihr Passwort zu erhalten. Sie leitet Ihren Browser zu einer sicheren Seite auf cathopic.com, weiter, wo Sie sich anmelden und die angeforderten Berechtigungen im Detail prüfen. Konto verbinden Wählen Sie in der anderen Anwendung dessen Cathopic-Connector aus und klicken Sie auf Verbinden oder Mit Cathopic anmelden. Bestätigen Sie, dass der Browser auf cathopic.comist. Melden Sie sich bei Cathopic ggf. an. Cathopic kehrt zur gleichen Berechtigungsanfrage zurück, statt Ihr Profil zu öffnen. Lesen Sie jede Berechtigung. Dazu können gehören: Identität des Kontos, Zugriff auf den Katalog, Abonnementguthaben oder die Möglichkeit, Ressourcen zu lizenzieren. Wählen Sie Zugriff erlauben. Cathopic sendet Sie nur zurück zu dem exakten Callback, der für diese Anwendung registriert ist. Sprache und Kontosicherheit Die Anwendung kann eine unterstützte Sprache für die Anmelde- und Berechtigungsbildschirme anfordern. Cathopic behält diese Sprache während der gesamten Verbindung bei. Die Anwendung erhält kurzlebige Tokens, niemals Ihr Passwort, und kann nur die Aktionen ausführen, die auf dem Berechtigungsbildschirm aufgelistet sind. Wenn Sie der Anfrage nicht vertrauen Wählen Sie Abbrechen. Genehmigen Sie die Verbindung nicht, wenn die Anwendung Ihnen nicht bekannt ist, die Berechtigungen unnötig erscheinen oder der Browser nicht die Cathopic-Domain anzeigt. Sie können den Zugriff später widerrufen unter Einstellungen → Entwickler / API → Verbundene Apps.

Question 18

Verwenden verbundene Apps meine Downloads, und wie kann ich sie trennen?

Accepted Answer

Das Suchen und Anzeigen von Wasserzeichen-Vorschauen verbraucht keinen Download. Ein Download kann nur dann verbraucht werden, wenn eine verbundene Anwendung Cathopic auffordert, eine kostenpflichtige Ressource zu lizenzieren. Wenn ein Download verbraucht wird Die Ressource ist kostenpflichtig, der Tarif umfasst ihren Typ, und weder du noch das aktuelle Team-Abo haben sie zuvor lizenziert. Der Tarif hat ein begrenztes Guthaben. Unbegrenzte Tarife erfassen die Lizenz, ohne eine Anzahl zu reduzieren. Die Originaldatei ist verfügbar. Cathopic überprüft dies, bevor das Guthaben geändert wird. Wenn kein zusätzlicher Download verbraucht wird Die Ressource ist kostenlos. Du oder ein anderes Teammitglied, das dasselbe Team-Abo nutzt, hat sie bereits lizenziert. Du forderst einen neuen Download-Link für eine bestehende Lizenz an. Die Anwendung versucht dieselbe Anfrage erneut mit demselben Idempotenzschlüssel. Teammitglieder verbrauchen das geteilte Guthaben des Teaminhabers. Cathopic ist immer die maßgebliche Quelle. Eine Anwendung trennen Öffnen Einstellungen → Entwickler / API → Verbundene Apps. Prüfe die Anwendung und ihre Berechtigungen. Klicken Trennen und bestätigen. Jedes aktive Zugriffs- und Refresh-Token für diese Anwendung wird sofort widerrufen. Bestehende Lizenzen und die Download-Historie bleiben erhalten.

Question 19

Häufige API-Fehlercodes

Accepted Answer

Das Verstehen von Fehlerantworten hilft Ihnen, Probleme schnell zu beheben. Hier sind die häufigsten Fehler, denen Sie begegnen werden. 400 Bad Request { "error": "media_id is required" } Ursachen: Fehlender erforderlicher Parameter Ungültiges Parameterformat Fehlerhaftes JSON Behebung: Prüfen Sie, ob Ihr Request-Body der API-Spezifikation entspricht unter api.cathopic.com/docs. 401 Unauthorized { "message": "Unauthorized" } oder { "error": "Unauthorized token" } Ursachen: Fehlender oder ungültiger API-Schlüssel Deaktivierter API-Schlüssel Falscher Header-Name Behebung: Vergewissern Sie sich, dass Ihr x-api-key-Header korrekt ist und der Schlüssel aktiv ist in Einstellungen → API. 404 Not Found { "error": "No file found for media_id 1234" } oder { "error": "Media item not found" } Ursachen: Ressource existiert nicht Ressource wurde gelöscht Falsches media_id Behebung: Prüfen Sie, ob die media_id existiert, indem Sie zuerst mit /resources suchen. 429 Too Many Requests { "error": "Limit exceed." } Ursachen: Zu viele Requests in kurzer Zeit Rate-Limit überschritten Behebung: Implementieren Sie exponentielles Backoff. Warten Sie und versuchen Sie es erneut mit zunehmenden Verzögerungen (1s, 2s, 4s usw.). 500 Internal Server Error { "error": "Internal server error" } Ursachen: Vorübergehendes Serverproblem Unerwartete Bedingung Behebung: Warten Sie einen Moment und versuchen Sie es erneut. Wenn das Problem weiterhin besteht, kontaktieren Sie den Support. Beispiel für Fehlerbehandlung async function searchWithErrorHandling(query) { try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query, page: 1, page_size: 20 }) }); if (!response.ok) { const error = await response.json(); switch (response.status) { case 400: console.error('Bad request:', error); break; case 401: console.error('Nicht autorisiert. Prüfen Sie Ihren API-Schlüssel.'); break; case 404: console.error('Ressource nicht gefunden:', error); break; case 429: console.error('Rate-Limit erreicht. Backoff wird implementiert...'); await sleep(5000); return searchWithErrorHandling(query); // Retry case 500: console.error('Serverfehler. Erneut versuchen in 10s...'); await sleep(10000); return searchWithErrorHandling(query); default: console.error('Unbekannter Fehler:', error); } throw new Error(`API error: ${response.status}`); } return await response.json(); } catch (error) { console.error('Request fehlgeschlagen:', error); throw error; } } Bei anhaltenden Fehlern prüfen Sie die vollständige API-Dokumentation oder kontaktieren Sie den Support.

Question 20

Rate-Limit-Fehler

Accepted Answer

Wenn Sie 429 Too Many Requests sehen, rufen Sie die API zu häufig auf. So gehen Sie richtig damit um. Der Fehler HTTP 429 Too Many Requests { "error": "Limit exceed." } Warum das passiert Rate Limits schützen die API vor übermäßiger Nutzung: Zu viele Anfragen in kurzer Zeit Aggressives Polling oder Scraping Keine Verzögerung zwischen Anfragen Gleichzeitige Anfragen ohne Drosselung Strategie mit exponentiellem Backoff Der beste Weg, Rate Limits zu handhaben, ist exponentielles Backoff: Warten Sie nach jedem Retry länger: async function fetchWithBackoff(url, options, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt + 1}/${maxRetries}`); await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { if (attempt === maxRetries - 1) throw error; } } throw new Error('Max retries exceeded'); } Rate Limits vermeiden Fügen Sie Verzögerungen zwischen Anfragen hinzu: // Schlecht: Anfragen im Schnellfeuer for (const id of mediaIds) { await api.getResource(id); // Keine Verzögerung } // Gut: Gedrosselte Anfragen for (const id of mediaIds) { await api.getResource(id); await sleep(500); // 500ms Verzögerung } Verarbeiten Sie Vorgänge im Batch: // In Batches von 10 verarbeiten, mit Verzögerungen const batchSize = 10; for (let i = 0; i < mediaIds.length; i += batchSize) { const batch = mediaIds.slice(i, i + batchSize); await Promise.all(batch.map(id => api.getResource(id))); if (i + batchSize < mediaIds.length) { await sleep(2000); // 2s zwischen Batches } } Antworten cachen: const cache = new Map(); async function getCachedResource(mediaId) { if (cache.has(mediaId)) { return cache.get(mediaId); } const data = await api.getResource(mediaId); cache.set(mediaId, data); return data; } Was Sie NICHT tun sollten ❌ Sofort erneut versuchen, ohne Verzögerung Parallele Anfragen ohne Begrenzung stellen 429-Fehler ignorieren Feste kurze Verzögerungen verwenden (immer exponentielles Backoff nutzen) Wenn die Probleme weiterhin bestehen Wenden Sie sich an den Developer Support, wenn Sie für Ihren Anwendungsfall berechtigt höhere Rate Limits benötigen. Geben Sie Details zu: Ihrer Anwendung und Ihrem Use Case Erwartetes Anfragevolumen Aktuelle Implementierung (mit Backoff)

Question 21

Zeitüberschreitungen und Netzwerkprobleme

Accepted Answer

Netzwerkprobleme können dazu führen, dass API-Anfragen fehlschlagen. So gehen Sie mit Zeitüberschreitungen und Verbindungsproblemen gelassen um. Passende Timeouts festlegen Setzen Sie immer Timeouts, um hängende Anfragen zu vermeiden: // JavaScript mit fetch const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); // 30s try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }), signal: controller.signal }); clearTimeout(timeout); return await response.json(); } catch (error) { clearTimeout(timeout); if (error.name === 'AbortError') { console.error('Request timed out after 30s'); } else { console.error('Network error:', error); } throw error; } // Python mit requests import requests from requests.exceptions import Timeout, RequestException try: response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'}, timeout=30 # 30 Sekunden ) return response.json() except Timeout: print('Request timed out after 30s') raise except RequestException as e: print(f'Network error: {e}') raise Häufige Netzwerkfehler Verbindungs-Timeout: Keine Verbindung zum Server möglich Meist ein Problem mit dem Netzwerk oder der Firewall Internetverbindung prüfen Überprüfen, ob die Firewall HTTPS für api.cathopic.com zulässt Lese-Timeout: Verbindung hergestellt, aber keine Antwort Der Server ist möglicherweise langsam oder überlastet Timeout erhöhen oder später erneut versuchen Fehler bei der DNS-Auflösung: api.cathopic.com kann nicht aufgelöst werden Problem mit dem DNS-Server Noch einmal versuchen oder DNS-Einstellungen prüfen Erneut versuchen mit Backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); const response = await fetch(url, { ...options, signal: controller.signal }); clearTimeout(timeout); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { const isLastAttempt = attempt === maxRetries - 1; if (isLastAttempt) { console.error(`All ${maxRetries} attempts failed`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Attempt ${attempt + 1} failed. Retrying in ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Empfohlene Timeout-Werte Verbindungs-Timeout: 10 Sekunden Lese-Timeout: 30 Sekunden /resources search: 30 Sekunden /confirm licensing: 30 Sekunden Netzwerkprobleme debuggen Verwenden Sie curl, um die Konnektivität zu testen: # Test basic connectivity curl -v https://api.cathopic.com/resources # Test with timeout curl --max-time 30 -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Prüfen Sie Folgendes: ✓ DNS löst api.cathopic.com auf ✓ SSL/TLS-Verbindung gelingt ✓ HTTP-Antwort erhalten ✓ Antwortzeit ist angemessen (<5s typischerweise) Wenn die Probleme weiterhin bestehen, wenden Sie sich an support und fügen Sie Details zur Netzwerkanalyse bei.

Question 22

Fehlgeschlagene Anfragen debuggen

Accepted Answer

Wenn Anfragen fehlschlagen, hilft systematisches Debugging dabei, das Problem schnell zu identifizieren. Detailliertes Logging aktivieren async function debugRequest(url, options) { console.log('=== API Request ==="); console.log('URL:', url); console.log('Method:', options.method); console.log('Headers:', { ...options.headers, 'x-api-key': options.headers['x-api-key']?.substring(0, 10) + '...' }); console.log('Body:', options.body); const startTime = Date.now(); try { const response = await fetch(url, options); const duration = Date.now() - startTime; console.log('=== API Response ==="); console.log('Status:', response.status, response.statusText); console.log('Duration:', duration + 'ms'); console.log('Headers:', Object.fromEntries(response.headers)); const data = await response.json(); console.log('Body:', data); return { response, data }; } catch (error) { console.error('=== Request Failed ==="); console.error('Error:', error.message); console.error('Duration:', Date.now() - startTime + 'ms'); throw error; } } Zuerst diese prüfen 1. API-Schlüssel ist korrekt: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. Header-Name ist exakt: // Muss kleingeschrieben 'x-api-key' sein headers: { 'x-api-key': apiKey, // ✓ Richtig 'X-API-Key': apiKey, // ✗ Falsch 'api-key': apiKey, // ✗ Falsch } 3. JSON ist gültig: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. Die Anfrage erreicht den Server: // Verwende die Browser-DevTools im Tab „Network“ oder curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Häufige Fehler Falscher Content-Type: // ✗ Falsch headers: { 'Content-Type': 'text/plain' } // ✓ Richtig headers: { 'Content-Type': 'application/json' } Body nicht als String umwandeln: // ✗ Falsch body: { query: 'test' } // ✓ Richtig body: JSON.stringify({ query: 'test' }) GET statt POST verwenden: // ✗ Alle Endpoints erfordern POST method: 'GET' // ✓ Richtig method: 'POST' Mit minimaler Anfrage testen Auf das Nötigste reduzieren, um das Problem einzugrenzen: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Leeres Objekt }); console.log(response.status); console.log(await response.json()); Wenn das funktioniert, füge schrittweise wieder Parameter hinzu, bis es fehlschlägt. Mit funktionierendem Beispiel vergleichen Teste mit curl, um deine Implementierung zu überprüfen: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Jesus", "page": 1, "page_size": 5}' Wenn curl funktioniert, dein Code aber nicht, vergleiche die exakten Header und den Body. Noch immer feststecken? Wende dich an den developer support und sende: Vollständige Fehlermeldung Anfrage-Header (verberge deinen vollständigen API-Schlüssel) Anfrage-Body Status und Body der Antwort Programmiersprache und HTTP-Bibliothek Code-Snippet (ohne Zugangsdaten offenzulegen)

Question 23

So kontaktieren Sie den Entwickler-Support

Accepted Answer

Brauchen Sie Hilfe bei Ihrer API-Integration? Unser Entwickler-Support-Team ist für Sie da. Wann Sie den Support kontaktieren sollten Wenden Sie sich an uns, wenn Sie Folgendes erleben: Authentifizierungsprobleme trotz Befolgen der Anleitungen Unerwartete Fehlermeldungen Probleme mit der Performance oder langsame Antworten Fragen zur Abrechnung oder Nutzung Höhere Rate Limits benötigen Klärung der Lizenzbedingungen Hilfe bei konkreten Integrationsszenarien So kontaktieren Sie uns Support-Seite: Besuchen Sie cathopic.com/support und füllen Sie das Kontaktformular aus. E-Mail (falls angegeben): Senden Sie die Details direkt an die E-Mail-Adresse für den Entwickler-Support, die in Ihrem API-Dashboard angegeben ist. Welche Informationen Sie angeben sollten Damit wir Ihnen schneller helfen können, geben Sie bitte Folgendes an: 1. Eine klare Beschreibung des Problems Was Sie tun möchten Was passiert im Vergleich zu dem, was Sie erwarten Wann das Problem begonnen hat 2. Technische Details Programmiersprache und Framework HTTP-Bibliothek oder SDK, das Sie verwenden Die letzten 4 Ziffern Ihres API-Schlüssels Fehlermeldungen (vollständiger Text) HTTP-Statuscodes 3. Codebeispiel (bereinigt) // Entfernen Sie Ihren vollständigen API-Schlüssel! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Nur die letzten 4 Ziffern 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Details zu Anfrage/Ausgabe Anfrage-Header Anfrage-Body Status der Antwort Body der Antwort Zeitpunkt des Problems Bevor Sie den Support kontaktieren Versuchen Sie zuerst diese Schritte, um Zeit zu sparen: Prüfen Sie die API-Dokumentation Lesen Sie die Fragen in diesem Hilfebereich Testen Sie mit curl, um das Problem einzugrenzen Verifizieren Sie, dass Ihr API-Schlüssel aktiv ist in Einstellungen → API Prüfen Sie, ob Ihre Zahlungsmethode gültig ist Reaktionszeit Wir bemühen uns, Anfragen an den Entwickler-Support an Werktagen innerhalb von 24–48 Stunden zu beantworten. Komplexe Probleme können zusätzliche Untersuchungszeit erfordern. Für dringende Probleme Wenn Sie einen kritischen Ausfall in der Produktion erleben: Markieren Sie Ihre Support-Anfrage als „Dringend“ Geben Sie Ihre Kontoe-Mail für eine priorisierte Identifizierung an Fügen Sie Impact-Details hinzu (Anzahl der betroffenen Nutzer, Umsatz-Auswirkung usw.) API-Status Bevor Sie einen Ausfall melden, prüfen Sie, ob es ein bekanntes Problem gibt: Testen Sie die grundlegende Konnektivität: curl https://api.cathopic.com/resources Prüfen Sie unsere Statusseite (falls verfügbar) Achten Sie auf Ankündigungen in Ihrem Kontodashboard Weitere Ressourcen Vollständige API-Dokumentation: api.cathopic.com/docs Kontodashboard: cathopic.com/settings/api Allgemeiner Support: cathopic.com/support Lizenzinformationen: cathopic.com/legal/license Wir sind hier, um Ihnen zu helfen, dass Ihre Integration erfolgreich ist!

Entwickler / API

Erste Schritte

API-Schlüssel, Abrechnung & Sicherheit

Katalog, Suche & Lizenzierung

OAuth-Anwendungen

Verbundene Apps

Fehlerbehebung