openapi/README.md

hightrusted CAPTURE — OpenAPI Specification

Status: v0.1 Preview — API stabil, Spec ist Single Source of Truth für alle SDKs

OpenAPI 3.1 Spezifikation der hightrusted CAPTURE API — forensische Web-Captures mit qualifiziertem Zeitstempel nach RFC 3161 / eIDAS Art. 41.

Diese Spec ist die maschinenlesbare Referenz, aus der wir alle anderen Artefakte ableiten: SDKs, Client-Bibliotheken, Postman-Collection, gerenderte Doku.

Made in Germany. Server in Deutschland. DSGVO-nativ. Kein US-Cloud-Anbieter in der Verarbeitungskette.

Inhalt

• openapi.yaml — die OpenAPI 3.1 Spec
• examples/ — Beispiel-Requests und -Responses für jeden Endpoint
• CHANGELOG.md — Versions-History der Spec

Validierung

# Mit redocly cli
npx @redocly/cli lint openapi.yaml

# Oder mit spectral
npx @stoplight/spectral-cli lint openapi.yaml

Doku rendern

# HTML-Doku mit Redoc bauen
npx @redocly/cli build-docs openapi.yaml -o ./docs/index.html

Ergebnis: statische HTML-Datei mit kompletter API-Doku, die du auf jedem Webserver ablegen kannst.

Client-Generierung

Aus dieser Spec lassen sich automatisch Clients für 50+ Sprachen erzeugen (siehe https://openapi-generator.tech). Wir pflegen offizielle Clients für Python, Node.js und PHP — siehe Verwandte Repositorys.

# Beispiel: Go-Client erzeugen
openapi-generator-cli generate \
  -i openapi.yaml \
  -g go \
  -o ./clients/go

Versionierung

API-Versionen sind im Pfad: /api/v1/...

• Breaking Changes → neue Major-Version (/api/v2), alte Major bleibt 24 Monate erreichbar
• Non-Breaking Changes (neue Felder, neue Endpoints) → ohne Versionssprung

Diese OpenAPI-Spec verfolgt die API 1:1. Änderungen sind in CHANGELOG.md nachvollziehbar.

Endpoints (Übersicht)

Endpoint	Beschreibung	Auth
POST /captures	Capture erstellen (sync/async/webhook)	Bearer
GET /captures/{id}	Status & Metadaten abrufen	Bearer
GET /captures/{id}/pdf	PDF herunterladen	Bearer
GET /captures/{id}/verify	Capture verifizieren	—
GET /usage	eigenen Verbrauch abrufen	Bearer

Webhook-Events

Event	Wann
capture.ready	PDF und Zeitstempel fertig
capture.failed	Fehler beim Rendern oder TSA

Webhook-Retry: 3 Versuche mit exponentiellem Backoff (1 min, 5 min, 30 min).

Verwandte Repositorys

Im selben Produkt (hightrusted-capture):

• postman — Postman Collection
• examples — Beispiel-Anwendungen
• python — Python-SDK
• node — Node.js-SDK
• php — PHP-SDK

Plattform-übergreifend (hightrusted):

• platform — Plattform-Übersicht, Architektur, Produkt-Liste
• developer-portal — gemeinsame Konventionen, Auth, Errors, Rate-Limits
• compliance — DSGVO, AGB-Templates, Whitepaper

Support

• Doku: https://capture.hightrusted.net/api/docs
• Status-Page: https://status.hightrusted.net
• Developer Support: developers@hightrusted.net
• Sicherheitslücken: siehe SECURITY.md

Lizenz

MIT — siehe LICENSE.

---

hightrusted GmbH — The European Trust Infrastructure. Made in Germany. DSGVO-nativ. eIDAS-konform.