API-Design für Dateiübertragung: bewährte RESTful-Praktiken

Die DSGVO verpflichtet Unternehmen in Art. 25 zu „Privacy by Design" — und das gilt auch für die APIs, über die Dateien das Netz durchqueren. Eine gut entworfene Dateiübertragungs-REST-API stellt fünf oder sechs Ressourcen bereit (Sessions, Parts, Shares, Downloads, Revocations), nutzt HTTP-Semantik ehrlich (POST zum Erstellen, PUT für idempotente Chunks, DELETE für Widerruf) und delegiert die eigentliche Byte-Bewegung an vorzeichnete Speicher-URLs, damit Ihr Server nie zum Bandbreiten-Engpass wird.

Authentifizierung nutzt kurzlebige Bearer Tokens über TLS 1.3, Ratenlimits unterscheiden zwischen Erstellung und Metadaten-Abfragen, Chunked Uploads folgen dem tus.io-Resumable-Muster oder S3-Multipart-Semantik, und Fehler folgen RFC 7807 Problem Details, damit Clients darauf programmatisch reagieren können.

Ressourcenmodell um Aktionen herum formen, nicht um Dateien

Ein häufiger Fehler ist, die API als Dateibaum zu modellieren. Dateiübertragungsdienste lassen sich besser als drei Ressourcen abbilden:

/sessions — ein laufender Upload, erstellt via POST, befüllt via Chunk-PUTs
/shares — eine abgeschlossene, adressierbare Übertragung mit Ablaufzeit und Download-Budget
/downloads — kurzlebige, signierte Zugriffs-Handles zum Abrufen von Bytes

Sessions werden durch eine complete-Aktion zu Shares; Shares werden durch Zeit oder Download-Budget zu abgelaufenen. Widerrufe erfolgen als PATCH auf einem Share oder DELETE mit einem Revocation-Token. Keine Substantive für „Datei" oder „Ordner" — das sind Implementierungsdetails des Speichers, nicht Ihr öffentlicher Vertrag.

Diese Form hält die API-Fläche klein (unter 10 Endpunkte), passt sauber zu HTTP-Caching, und lässt Sie Speicher-Backends tauschen, ohne Clients zu brechen.

Authentifizierung und Autorisierungsmuster

Für nutzerorientierte APIs stellen Sie kurzlebige JWTs aus (15-Minuten-TTL), signiert mit EdDSA, und erneuern sie via sicherem HttpOnly-Cookie. Das Token gehört in Authorization: Bearer, nie in Query Strings, wo es in Logs landet.

Für Machine-to-Machine ist HMAC-SHA256-Request-Signing besser als Bearer Tokens, da es den Besitz eines Schlüssels nachweist, ohne ihn zu senden. AWS SigV4 ist das Referenzdesign:

Authorization: HEX4-HMAC-SHA256 
  Credential=AKIA.../20261202/eu/transfer/hex4_request,
  SignedHeaders=host;x-hex-date;x-hex-content-sha256,
  Signature=...

Für vorzeichnete Download-URLs sollten TTLs Minuten, nicht Stunden betragen. Ein 15-Minuten-Fenster balanciert Nutzbarkeit gegen das Risiko einer weitergeleiteten URL. IP-Sperren nur einsetzen, wenn CGNAT-Nutzer kein Problem darstellen — meistens tun sie es.

Chunked Uploads und Multipart-Semantik

Zwei glaubwürdige Protokolle für wiederaufnehmbare Chunked Uploads existieren: tus.io (IETF-Draft, Upload-Offset- und Upload-Length-Header) und S3 Multipart (PartNumber, UploadId, ETag). Wählen Sie eines und halten Sie daran fest. Ein eigenes Protokoll zu erfinden scheint verlockend und endet schlecht, wenn Sie partielle Schreibvorgänge, nicht-sequentielle Chunks und aufgegebene Sessions behandeln müssen.

Das tus-Muster in REST-Form:

POST   /sessions              -> 201, Location: /sessions/abc
HEAD   /sessions/abc          -> 200, Upload-Offset: 104857600
PATCH  /sessions/abc          -> 204, body = nächster Chunk
POST   /sessions/abc/complete -> 201, Location: /shares/xyz
DELETE /sessions/abc          -> 204

Chunk-Größen-Grenzen: 5 MB Minimum für S3-Multipart-Kompatibilität, 100 MB Maximum, um Retry-Kosten zu begrenzen, 8 MB als Standard. Chunks, die nicht mit dem angekündigten Offset übereinstimmen, mit HTTP 409 Conflict plus Problem-Dokument ablehnen.

Ratenlimits, die echten Missbrauch widerspiegeln

Ratenlimits müssen nach Endpunkt-Kosten variieren:

POST /sessions: 20 pro IP pro Stunde (teuer — belegt Speicher)
PATCH /sessions/:id: 10.000 pro Stunde pro Session (günstig — schreibt Bytes)
GET /shares/:id: 1.000 pro IP pro Stunde (Metadaten-Abfrage)
GET /shares/:id/download: 100 pro IP pro Stunde (Egress-Kosten)

Limits am Edge durchsetzen (Cloudflare, Fastly) als Boden-Schutz, und eine zweite Schicht auf Anwendungsebene für Burst-Kontrolle. 429 zurückgeben mit Retry-After in Sekunden. Ratenlimit-Header auch bei erfolgreichen Antworten mitsenden:

RateLimit-Limit: 20
RateLimit-Remaining: 17
RateLimit-Reset: 2843

Fehlerantworten, auf die Clients reagieren können

RFC 7807 Problem Details ist der Standard. Jeder Fehler gibt Content-Type: application/problem+json zurück:

{
  "type": "https://api.example.com/errors/chunk-offset-mismatch",
  "title": "Chunk-Offset-Abweichung",
  "status": 409,
  "detail": "Server erwartete Offset 5242880, erhielt 4194304.",
  "expected_offset": 5242880,
  "session_id": "abc123"
}

Die type-URI muss dokumentiert und stabil sein — darauf matchen Clients. title ist generisch; detail ist spezifisch. Benutzerdefinierte Felder ergänzen maschinell verwertbaren Kontext. Keine Stack Traces, Dateipfade oder interne IDs in Fehlern preisgeben.

HTTP-Status-Codes ehrlich zuordnen: 400 für fehlerhafte Eingaben, 401 für fehlende Authentifizierung, 403 für authentifiziert-aber-unberechtigt, 404 nur wenn die Ressource nie existiert hat (410 Gone für abgelaufene Shares), 413 für Quota-Überschreitung, 429 für Ratenlimits, 500 für Bugs, 503 für Wartung.

Content Negotiation und Streaming

Upload-Endpunkte sollten application/octet-stream akzeptieren und Content-Length erfordern. multipart/form-data für Chunk-Uploads ablehnen — es fügt Parse-Overhead hinzu. Content-Range für tus-artige partielle Schreibvorgänge akzeptieren.

Download-Endpunkte sollten HTTP-Range-Anfragen (RFC 7233) für wiederaufnehmbare Downloads unterstützen:

GET /shares/xyz/blob
Range: bytes=104857600-209715199
-> 206 Partial Content
   Content-Range: bytes 104857600-209715199/2147483648

Das ermöglicht Browsern, einen 2-GB-Download nach einem WLAN-Ausfall fortzuführen. Die meisten S3-kompatiblen Stores bedienen Range-Anfragen nativ — Ihre API muss nur weiterleiten oder vorsignieren.

Versionierung ohne Schuldenakkumulation

Versionierung via URL-Pfad (/v1/sessions), nicht via Header. Pfad-Versionierung ist in Logs sichtbar, cachebar und einfacher zu debuggen als Accept: application/vnd.example.v1+json. v1 mindestens 24 Monate nach dem Start von v2 unterstützen. Felder frei hinzufügen (Clients müssen unbekannte ignorieren); niemals Felder in einer stabilen Version entfernen oder umbenennen.

Bei notwendigen Breaking Changes v1 und v2 12 Monate parallel betreiben, einen Sunset-Header auf v1-Antworten gemäß RFC 8594 ausgeben und Migrationsleitfäden mit konkreten Vorher-Nachher-Beispielen veröffentlichen.

Beobachtbarkeit und Debugfähigkeit

Jede Antwort sollte eine Korrelations-ID enthalten (X-Request-ID), die aus der Anfrage übernommen oder erzeugt wird. ID, Client-IP (gehasht falls datenschutzsensitiv), Endpunkt, Status und Dauer in strukturiertem JSON loggen. Keine Request-Bodies loggen — so landen Verschlüsselungsschlüssel in Datadog.

Metriken pro Endpunkt ausgeben: Anfragezahl, p50/p95/p99 Latenz, Fehlerrate, Bytes ein/aus. Bei p99-Latenz-Spitzen und 5xx-Rate über Baseline alarmieren. Traces via OpenTelemetry zeigen den Anfrage-Fluss über API, Speicher und Datenbank.

HexaTransfer setzt die beschriebenen Muster ein — kurze Ressourcen, tus-artige Chunk-Uploads, Problem-Details-Fehler, 15-Minuten-vorzeichnete Downloads, RateLimit-Header. Testen Sie es unter https://hexatransfer.com — kostenlos, kein Konto, bis 10 GB.

Dokumentation, die der Realität entspricht

Veröffentlichen Sie eine OpenAPI-3.1-Spezifikation zusammen mit der API und pflegen Sie sie im selben Repository wie den Server-Code, damit Schema-Abweichungen zum PR-Review-Problem statt zur Produktionsüberraschung werden. Mindestens ein SDK (TypeScript oder Python) aus der Spezifikation generieren und in eigenen Beispielen verwenden — SDK-Bugs enthüllen Spec-Bugs schnell. curl-Beispiele für jeden Endpunkt einschließen, einen Quickstart, der eine echte Datei in unter 20 Zeilen hochlädt, und eine Seite, die jeden Fehler-type-URI dokumentiert. Eine API, die Entwickler an einem Nachmittag integrieren können, landet in zehnmal mehr Produkten als eine, die eine Woche Reverse Engineering erfordert.