Caspar Manufaktur: API-Versionierung und Betrieb
Stand: 1. Oktober 2026. Diese Regeln gelten für die öffentliche Caspar Agent API.
Versioning and deprecation policy
Die REST-Schnittstelle verwendet die Hauptversion /wp-json/caspar-agent/v1/. Neue optionale Felder und neue Endpunkte können innerhalb von v1 hinzukommen. Clients sollten unbekannte Antwortfelder ignorieren. Änderungen, die vorhandene Pflichtfelder, deren Bedeutung oder bestehende Aufrufe inkompatibel verändern, werden als neue Hauptversion veröffentlicht.
Für planbare Abschaltungen einer unterstützten Hauptversion ist eine Ankündigung mit mindestens 90 Tagen Vorlauf vorgesehen. Die Ankündigung wird hier und in der OpenAPI-Dokumentation veröffentlicht und nennt den betroffenen Endpunkt, das Abschaltdatum und eine Migrationsempfehlung. Für einen tatsächlich abgekündigten Endpunkt werden die HTTP-Header Deprecation und Sunset bereitgestellt. Derzeit ist keine Abschaltung von v1 angekündigt. Dringende Sicherheitsmaßnahmen können eine kürzere Frist erfordern.
Die Versionsnummer des OpenAPI-Dokuments bezeichnet dessen Dokumentationsstand; sie ist unabhängig von der installierten Plugin-Version.
Zugriff und Umfang
Materialinformationen, Empfehlungen und Unternehmensinformationen sind ohne API-Schlüssel lesbar. Der Material-Endpunkt liefert die vollständige kuratierte Auswahl der API und keine paginierte Massendatenliste. Sie ist eine Auswahl, nicht zwingend das gesamte Materialangebot der Website.
Projektübergaben liefern einen Link zu einer menschlich betreuten Anfrage oder zum Wallcheck. Sie lösen keine Bestellung, Zahlung oder Produktion aus und übermitteln keine personenbezogenen Projektdaten.
Idempotency-Key und Wiederholungen
POST /wp-json/caspar-agent/v1/handoffs verlangt einen Idempotency-Key mit 8–255 Zeichen aus Buchstaben, Ziffern, Punkt, Unterstrich, Doppelpunkt oder Bindestrich. Derselbe Schlüssel darf ausschließlich für Wiederholungen mit demselben next_step verwendet werden. Für einen anderen Vorgang ist ein neuer Schlüssel erforderlich.
Die bestehende Implementierung speichert die Antwort in einem WordPress- Transient mit einer Ablaufzeit von 24 Stunden (86400 Sekunden). Solange dieser Eintrag vorhanden ist, liefert eine Wiederholung die gespeicherte Antwort mit HTTP 200 und Idempotency-Replayed: true; ein neuer Eintrag liefert HTTP 201. Caches können einen Transient vor Ablauf entfernen. Die 24 Stunden sind daher keine garantierte Mindestaufbewahrung oder Zusage einer atomaren Verarbeitung gleichzeitiger Anfragen. Nach Verlust oder Ablauf des Eintrags kann eine neue Handoff-ID entstehen. Die Übergabe bleibt ein Link ohne Bestellwirkung.
Fehler und Retry-Verhalten
Die Caspar-REST-Endpunkte verwenden das WordPress-Fehlerformat mit code, message und gegebenenfalls data.status. Bei HTTP 400 muss der Client seine Eingabe korrigieren. Bei vorübergehenden Netzwerk- oder Serverfehlern sollten Clients eine begrenzte Anzahl Wiederholungen mit zunehmenden Pausen verwenden. Bei HTTP 429 ist ein vorhandener Retry-After-Header zu beachten.
Es werden keine festen Rate-Limits oder verfügbaren Anfragekontingente zugesichert. Angaben hierzu müssen dem tatsächlich durchgesetzten Serverlimit entsprechen; statische Beispielwerte sind keine Kontingentanzeige.
Verfügbarkeit und Support
Die öffentliche API wird als Best-Effort-Service angeboten. Es besteht keine veröffentlichte Verfügbarkeitsgarantie oder SLA. Clients sollten Lesedaten kurz zwischenspeichern und bei Nichterreichbarkeit die persönliche Beratung anbieten.
Gemeinsame OpenAPI-Spezifikation Developer Portal Agent-Hinweise Support: info@caspar-manufaktur.de Persönliche Beratung