File Upload API

Test-Zugangsdaten

Nach den Migrationen kann der Administrator deterministisch angelegt oder aktualisiert werden:

php artisan migrate
./bin/make-demo-admin.sh

Das Skript ist idempotent. Ein bestehender Account mit demo@iab.de behaelt seine ID und seinen Namen, erhaelt aber erneut Administratorrechte und das oben dokumentierte Passwort.

Authentication

Alle Verwaltungsendpunkte unter /api/files erfordern einen Bearer-Token. Die oeffentlichen Leseendpunkte unter /api/public/files benoetigen keinen Token. Token anfordern via:

POST /api/tokens
Content-Type: application/json

{
  "email": "demo@iab.de",
  "password": "winter123456",
  "token_name": "my-client"
}

Response 201 Created

{ "token": "1|xxxxxxxxxxxx" }

Token widerrufen:

DELETE /api/tokens/current
Authorization: Bearer <token>

Response 204 No Content

Berechtigungen

• Normale Benutzer koennen nur eigene Dateien auflisten, lesen, aktualisieren, ersetzen, herunterladen und loeschen. Zugriffe auf fremde IDs liefern 404.
• Administratoren koennen Dateien aller Benutzer und unabhaengig von freigabe verwalten.
• Administratoren koennen auch unveroeffentlichte oder noch gesperrte Inhalte herunterladen.
• Die Administratorrolle wird nicht ueber die HTTP-API vergeben. Dafuer dient ./bin/make-demo-admin.sh.

Endpoints

CRUD-Uebersicht

Datei erstellen (Create)

POST /api/files
Authorization: Bearer <token>
Content-Type: multipart/form-data

Der path definiert die Ordnerstruktur. Erlaubte Zeichen: a-z A-Z 0-9 . _ - und / als Trennzeichen. Kein führender oder abschließender Slash, keine ..-Segmente.

Beispiel

curl -X POST https://repo.iab.de/api/files \
  -H "Authorization: Bearer <token>" \
  -F "files[]=@bericht.pdf" \
  -F "files[]=@daten.xlsx" \
  -F "path=projekte/2026/q1"

Response 201

{
    "files": [
        {
            "id": "018f1a2b-...",
            "aktiv_id": "AKT-2026-001",
            "original_name": "bericht.pdf",
            "path": "projekte/2026/q1",
            "mime_type": "application/pdf",
            "size": 204800,
            "reprotyp": "forschungsbericht",
            "titel": "Arbeitsmarktbericht 2026",
            "beschreibung": null,
            "autoren": "Max Mustermann",
            "sachschlagwoerter": null,
            "iab_themen": null,
            "sperrfrist": null,
            "reihenfolge": 0,
            "freigabe": true,
            "erstellt_von": "Redaktion Dashboard",
            "freigegeben_von": "Admin Dashboard",
            "created_at": "2026-04-30T10:00:00.000000Z"
        }
    ]
}

Datei herunterladen

GET /api/files/{id}/download
Authorization: Bearer <token>

Liefert die Datei als Download mit korrektem Content-Type und originalem Dateinamen. Normale Benutzer koennen nur eigene Dateien herunterladen (sonst 404). Bei freigabe=false oder sperrfrist in der Zukunft folgt fuer normale Benutzer 403; Administratoren duerfen diese Inhalte herunterladen.

Bei Audio-Dateien wird der server-seitig erkannte MIME-Typ im Content-Type des Downloads verwendet. Der Dateiinhalt wird beim Upload, Download und beim Ersetzen des Inhalts nicht umgewandelt. Je nach fileinfo-Erkennung kann eine WAV-Datei als audio/x-wav, audio/wav oder audio/wave gespeichert werden. OGG wird als audio/ogg und MP3 als audio/mpeg gespeichert.

curl -OJ "https://repo.iab.de/api/files/018f1a2b-.../download" \
  -H "Authorization: Bearer <token>"

Datei lesen (Read Single)

GET /api/files/{id}
Authorization: Bearer <token>

Gibt die Metadaten einer einzelnen erlaubten Datei zurueck. Normale Benutzer sehen nur eigene, Administratoren alle Datensaetze, auch bei freigabe=false.

Response 200

{
    "id": "018f1a2b-...",
    "aktiv_id": "AKT-2026-001",
    "original_name": "bericht.pdf",
    "path": "projekte/2026/q1",
    "mime_type": "application/pdf",
    "size": 204800,
    "reprotyp": "forschungsbericht",
    "titel": "Arbeitsmarktbericht 2026",
    "beschreibung": null,
    "autoren": "Max Mustermann",
    "sachschlagwoerter": null,
    "iab_themen": null,
    "sperrfrist": null,
    "reihenfolge": 0,
    "freigabe": true,
    "erstellt_von": "Redaktion Dashboard",
    "freigegeben_von": "Admin Dashboard",
    "created_at": "2026-04-30T10:00:00.000000Z",
    "updated_at": "2026-04-30T10:00:00.000000Z"
}

curl "https://repo.iab.de/api/files/018f1a2b-..." \
  -H "Authorization: Bearer <token>"

Dateien auflisten

GET /api/files
Authorization: Bearer <token>

Gibt fuer normale Benutzer alle eigenen Uploads und fuer Administratoren die Uploads aller Benutzer zurueck. Die Liste ist nach Hochladezeitpunkt sortiert (neueste zuerst) und auf 100 Eintraege pro Seite paginiert. Mit freigabe=0 kann das Admin-Dashboard gezielt unveroeffentlichte Datensaetze abrufen.

Optionale Filter (kombinierbar):

since – Zeitpunkt mit Zeitzone

Der Wert muss ISO 8601 sein. Ohne Offset wird UTC angenommen – bei lokaler Zeit (z. B. Europe/Berlin, CEST = UTC+2) immer den Offset mitsenden:

# Alle Uploads seit 30. April 12:00 Uhr Berliner Zeit
curl "https://repo.iab.de/api/files?since=2026-04-30T12:00:00%2B02:00" \
  -H "Authorization: Bearer <token>"

# Alternativ direkt als UTC
curl "https://repo.iab.de/api/files?since=2026-04-30T10:00:00Z" \
  -H "Authorization: Bearer <token>"

curl "https://repo.iab.de/api/files?aktiv_id=AKT-2026-001" \
  -H "Authorization: Bearer <token>"

curl "https://repo.iab.de/api/files?path=projekte/2026" \
  -H "Authorization: Bearer <token>"

Datei aktualisieren (Update)

PATCH /api/files/{id}
Authorization: Bearer <token>
Content-Type: application/json

Aktualisiert Metadaten einer bestehenden eigenen Datei. Es werden nur uebergebene Felder geaendert (partielles Update). Optional kann auch path geaendert werden.

curl -X PATCH "https://repo.iab.de/api/files/018f1a2b-..." \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "titel": "Arbeitsmarktbericht 2026 (final)",
    "freigabe": true,
    "reihenfolge": 10
  }'

Response 200

{
    "id": "018f1a2b-...",
    "titel": "Arbeitsmarktbericht 2026 (final)",
    "freigabe": true,
    "reihenfolge": 10,
    "updated_at": "2026-05-01T09:15:00.000000Z"
}

Dateiinhalt ersetzen

POST /api/files/{id}/content
Authorization: Bearer <token>
Content-Type: multipart/form-data

Ersetzt nur den gespeicherten Inhalt einer Datei. Die Datensatz-ID, der Besitzer, created_at und alle Fachmetadaten bleiben erhalten. Aktualisiert werden original_name, stored_path, mime_type, size und updated_at. Nach erfolgreicher Aktualisierung wird der alte Inhalt geloescht.

curl -X POST "https://repo.iab.de/api/files/018f1a2b-.../content" \
  -H "Authorization: Bearer <token>" \
  -F "file=@daten-korrigiert.csv"

Response 200: Vollstaendige Metadaten des bestehenden Datensatzes mit unveraenderter id und aktualisiertem updated_at.

Datei löschen

DELETE /api/files/{id}
Authorization: Bearer <token>

Loescht Datei und Metadaten-Eintrag. Normale Benutzer koennen nur eigene Dateien loeschen (sonst 404), Administratoren auch fremde Dateien.

Oeffentliche Lese-API

Die folgenden Endpunkte sind ohne Token erreichbar. Sie liefern ausschliesslich Datensaetze mit freigabe=true; ein Query-Parameter kann diese Einschraenkung nicht umgehen.

Die Liste unterstuetzt die Filter path, aktiv_id, since und reprotyp wie die geschuetzte Liste. Eine zukuenftige sperrfrist versteckt die Metadaten nicht, blockiert aber den oeffentlichen Download mit 403. Unveroeffentlichte IDs liefern bei Einzelansicht und Download 404.

Die oeffentlichen JSON-Antworten enthalten updated_at, damit Clients ersetzte Inhalte erkennen koennen. Interne Felder wie user_id, stored_path, erstellt_von und freigegeben_von werden nicht ausgegeben. Antworten setzen Cache-Control: public, max-age=0, must-revalidate.

curl "https://repo.iab.de/api/public/files?reprotyp=datensatz"
curl -OJ "https://repo.iab.de/api/public/files/018f1a2b-.../download"

Erlaubte Dateitypen

Der MIME-Typ wird server-seitig anhand der Datei-Magic-Bytes geprüft, nicht anhand des Client-Headers.

Limits

Fehler

Beispiel Validierungsfehler

{
    "message": "The files.0 field must be a file of type: pdf, txt, ...",
    "errors": {
        "files.0": ["Unsupported file type."]
    }
}

Speicherstruktur

Dateien werden privat gespeichert (nicht öffentlich erreichbar) unter:

storage/app/private/uploads/{user_id}/{YYYY}/{MM}/{DD}/{hashname}

Der virtuelle Metadatenwert path beeinflusst den physischen Speicherpfad nicht. Der Dateiname wird als eindeutiger Hash gespeichert:

storage/app/private/uploads/1/2026/04/30/aB3xYz9kQ2mN4pR7.pdf