Stefan Schmidt-Egermann
b13fba1d75
- Vollständige OpenAPI 3.1 Spezifikation - Alle Endpoints, Schemas, Webhooks, Error-Responses - Beispiel-Requests für minimal/async/webhook-Modi - Initiale CHANGELOG.md
114 lines
4 KiB
Markdown
114 lines
4 KiB
Markdown
# hightrusted CAPTURE — OpenAPI Specification
|
|
|
|
> **Status:** v1.0.0 — Single Source of Truth für alle SDKs
|
|
|
|
OpenAPI 3.1 Spezifikation der [hightrusted CAPTURE API](https://capture.hightrusted.net) —
|
|
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.
|
|
|
|
## Inhalt
|
|
|
|
- `openapi.yaml` — die OpenAPI 3.1 Spec
|
|
- `CHANGELOG.md` — Versions-History
|
|
|
|
## Validieren
|
|
|
|
```bash
|
|
# Mit redocly cli
|
|
npx @redocly/cli lint openapi.yaml
|
|
|
|
# Oder mit spectral
|
|
npx @stoplight/spectral-cli lint openapi.yaml
|
|
```
|
|
|
|
## Doku rendern
|
|
|
|
```bash
|
|
# HTML-Doku mit Redoc bauen
|
|
npx @redocly/cli build-docs openapi.yaml -o ./docs/index.html
|
|
|
|
# Mit Swagger UI lokal anzeigen
|
|
npx swagger-ui-watcher openapi.yaml
|
|
```
|
|
|
|
## Client-Generierung
|
|
|
|
Aus dieser Spec lassen sich automatisch Clients für 50+ Sprachen erzeugen:
|
|
|
|
```bash
|
|
npx @openapitools/openapi-generator-cli generate \
|
|
-i openapi.yaml \
|
|
-g go \
|
|
-o ./clients/go
|
|
```
|
|
|
|
Wir pflegen offizielle Clients **handgeschrieben** für Python, Node.js und PHP
|
|
— sie sind idiomatischer als generierte Clients und haben getestete
|
|
Webhook-Verifikation, typisierte Exceptions und ergonomische APIs.
|
|
|
|
## Endpoints (Übersicht)
|
|
|
|
| Endpoint | Beschreibung | Auth |
|
|
|--------------------------------|--------------------------------------------|--------|
|
|
| `POST /captures` | Capture erstellen (sync/async/webhook) | Bearer |
|
|
| `GET /captures` | Captures auflisten (paginiert) | Bearer |
|
|
| `GET /captures/{id}` | Status & Metadaten abrufen | Bearer |
|
|
| `GET /captures/{id}/pdf` | PDF herunterladen | Bearer |
|
|
| `POST /verify` | Verifizieren (per ID, URL, oder PDF) | — |
|
|
| `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).
|
|
Signaturverifikation per HMAC-SHA-256 (`X-Hightrusted-Signature: sha256=...`).
|
|
|
|
## 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.
|
|
|
|
## Verwandte Repositorys
|
|
|
|
**Im selben Produkt** ([`hightrusted-capture`](https://git.hightrusted.net/hightrusted-capture)):
|
|
|
|
- [`postman`](https://git.hightrusted.net/hightrusted-capture/postman) — Postman Collection
|
|
- [`examples`](https://git.hightrusted.net/hightrusted-capture/examples) — Beispiel-Anwendungen
|
|
- [`python`](https://git.hightrusted.net/hightrusted-capture/python) — Python-SDK
|
|
- [`node`](https://git.hightrusted.net/hightrusted-capture/node) — Node.js-SDK
|
|
- [`php`](https://git.hightrusted.net/hightrusted-capture/php) — PHP-SDK
|
|
|
|
**Plattform-übergreifend** ([`hightrusted`](https://git.hightrusted.net/hightrusted)):
|
|
|
|
- [`platform`](https://git.hightrusted.net/hightrusted/platform)
|
|
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal)
|
|
- [`compliance`](https://git.hightrusted.net/hightrusted/compliance)
|
|
|
|
## Support
|
|
|
|
- **Doku:** https://capture.hightrusted.net/api/docs
|
|
- **Status:** https://status.hightrusted.net
|
|
- **Developer Support:** developers@hightrusted.net
|
|
|
|
## Lizenz
|
|
|
|
MIT — siehe [LICENSE](./LICENSE). Spec und Beispiele dürfen frei für eigene
|
|
Implementierungen genutzt werden.
|
|
|
|
---
|
|
|
|
**hightrusted GmbH** — *The European Trust Infrastructure.*
|
|
Made in Germany. DSGVO-nativ. eIDAS-konform.
|