113 lines
4.1 KiB
Markdown
113 lines
4.1 KiB
Markdown
# 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](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. 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
|
|
|
|
```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
|
|
```
|
|
|
|
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](#verwandte-repositorys).
|
|
|
|
```bash
|
|
# 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`](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) — Plattform-Übersicht, Architektur, Produkt-Liste
|
|
- [`developer-portal`](https://git.hightrusted.net/hightrusted/developer-portal) — gemeinsame Konventionen, Auth, Errors, Rate-Limits
|
|
- [`compliance`](https://git.hightrusted.net/hightrusted/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](./SECURITY.md)
|
|
|
|
## Lizenz
|
|
|
|
MIT — siehe [LICENSE](./LICENSE).
|
|
|
|
---
|
|
|
|
**hightrusted GmbH** — *The European Trust Infrastructure.*
|
|
Made in Germany. DSGVO-nativ. eIDAS-konform.
|