# File Upload API **API-Basis (Produktion):** [https://repo.iab.de](https://repo.iab.de) ## Test-Zugangsdaten | Feld | Wert | | ------------ | -------------- | | **Email** | `demo@iab.de` | | **Password** | `winter123456` | --- ## Authentication All upload endpoints require a Bearer token. Token via: ```http POST /api/tokens Content-Type: application/json { "email": "demo@iab.de", "password": "winter123456", "token_name": "my-client" } ``` Response: ```json { "token": "1|xxxxxxxxxxxx" } ``` Token widerrufen: ```http DELETE /api/tokens/current Authorization: Bearer ``` --- ## Endpoints ### CRUD-Uebersicht | Operation | HTTP | Endpoint | Beschreibung | | ------------- | -------- | ----------------- | --------------------------------------------- | | Create | `POST` | `/api/files` | Eine oder mehrere Dateien hochladen | | Read (List) | `GET` | `/api/files` | Eigene Dateien paginiert auflisten | | Read (Single) | `GET` | `/api/files/{id}` | Metadaten einer einzelnen Datei lesen | | Update | `PATCH` | `/api/files/{id}` | Metadaten (und optional `path`) aktualisieren | | Delete | `DELETE` | `/api/files/{id}` | Datei inkl. Metadaten loeschen | --- ### Datei erstellen (Create) ``` POST /api/files Authorization: Bearer Content-Type: multipart/form-data ``` | Feld | Typ | Pflicht | Beschreibung | | ------------------- | ------- | ------- | -------------------------------------------------- | | `files[]` | File(s) | ja | 1–25 Dateien, je max. 200 MB | | `path` | string | nein | Virtueller Zielpfad, z. B. `projekte/2026/q1` | | `aktiv_id` | string | nein | Externe Aktivitäts- oder Vorgangsnummer | | `reprotyp` | string | nein | Repräsentationstyp, z. B. `forschungsbericht` | | `titel` | string | nein | Titel der Datei/Publikation | | `beschreibung` | string | nein | Kurzbeschreibung (max. 5000 Zeichen) | | `autoren` | string | nein | Autorenangabe(n) | | `sachschlagwoerter` | string | nein | Sachschlagwörter | | `iab_themen` | string | nein | IAB-Themenbereich | | `sperrfrist` | date | nein | Sperrdatum (ISO 8601), Download bis dahin gesperrt | | `reihenfolge` | integer | nein | Sortierreihenfolge (default: 0) | | `freigabe` | boolean | nein | Ob die Datei abrufbar ist (default: `true`) | 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** ```bash curl -X POST https://repo.iab.de/api/files \ -H "Authorization: Bearer " \ -F "files[]=@bericht.pdf" \ -F "files[]=@daten.xlsx" \ -F "path=projekte/2026/q1" ``` **Response `201`** ```json { "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, "created_at": "2026-04-30T10:00:00.000000Z" } ] } ``` --- ### Datei herunterladen ``` GET /api/files/{id}/download Authorization: Bearer ``` Liefert die Datei als Download mit korrektem `Content-Type` und originalem Dateinamen. Nur eigene Dateien sind abrufbar (sonst `404`). Bei `freigabe=false` oder `sperrfrist` in der Zukunft → `403`. ```bash curl -OJ "https://repo.iab.de/api/files/018f1a2b-.../download" \ -H "Authorization: Bearer " ``` --- ### Datei lesen (Read Single) ``` GET /api/files/{id} Authorization: Bearer ``` Gibt die Metadaten einer einzelnen eigenen Datei zurueck. Nur eigene Dateien sind abrufbar (sonst `404`). **Response `200`** ```json { "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, "created_at": "2026-04-30T10:00:00.000000Z", "updated_at": "2026-04-30T10:00:00.000000Z" } ``` ```bash curl "https://repo.iab.de/api/files/018f1a2b-..." \ -H "Authorization: Bearer " ``` --- ### Dateien auflisten ``` GET /api/files Authorization: Bearer ``` Gibt alle eigenen Uploads zurück, sortiert nach Hochladezeitpunkt (neueste zuerst), paginiert (100 pro Seite). **Optionale Filter (kombinierbar):** | Parameter | Beschreibung | Beispiel | | ---------- | ------------------------------- | ----------------------------------- | | `path` | Pfad-Präfix | `path=projekte/2026` | | `aktiv_id` | Exakte Aktivitäts-ID | `aktiv_id=AKT-2026-001` | | `since` | Nur Dateien ab diesem Zeitpunkt | `since=2026-04-30T12:00:00%2B02:00` | | `freigabe` | Nach Freigabe filtern | `freigabe=1` oder `freigabe=0` | | `reprotyp` | Nach Repräsentationstyp filtern | `reprotyp=forschungsbericht` | **`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: ```bash # 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 " ``` ```bash # Alternativ direkt als UTC curl "https://repo.iab.de/api/files?since=2026-04-30T10:00:00Z" \ -H "Authorization: Bearer " ``` ```bash curl "https://repo.iab.de/api/files?aktiv_id=AKT-2026-001" \ -H "Authorization: Bearer " ``` ```bash curl "https://repo.iab.de/api/files?path=projekte/2026" \ -H "Authorization: Bearer " ``` --- ### Datei aktualisieren (Update) ``` PATCH /api/files/{id} Authorization: Bearer Content-Type: application/json ``` Aktualisiert Metadaten einer bestehenden eigenen Datei. Es werden nur uebergebene Felder geaendert (partielles Update). Optional kann auch `path` geaendert werden. | Feld | Typ | Pflicht | Beschreibung | | ------------------- | ------- | ------- | ---------------------------------------- | | `path` | string | nein | Neuer virtueller Zielpfad | | `aktiv_id` | string | nein | Externe Aktivitaets- oder Vorgangsnummer | | `reprotyp` | string | nein | Repraesentationstyp | | `titel` | string | nein | Titel der Datei/Publikation | | `beschreibung` | string | nein | Kurzbeschreibung (max. 5000 Zeichen) | | `autoren` | string | nein | Autorenangabe(n) | | `sachschlagwoerter` | string | nein | Sachschlagwoerter | | `iab_themen` | string | nein | IAB-Themenbereich | | `sperrfrist` | date | nein | Sperrdatum (ISO 8601) | | `reihenfolge` | integer | nein | Sortierreihenfolge | | `freigabe` | boolean | nein | Ob die Datei abrufbar ist | ```bash curl -X PATCH "https://repo.iab.de/api/files/018f1a2b-..." \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "titel": "Arbeitsmarktbericht 2026 (final)", "freigabe": true, "reihenfolge": 10 }' ``` **Response `200`** ```json { "id": "018f1a2b-...", "titel": "Arbeitsmarktbericht 2026 (final)", "freigabe": true, "reihenfolge": 10, "updated_at": "2026-05-01T09:15:00.000000Z" } ``` --- ### Datei löschen ``` DELETE /api/files/{id} Authorization: Bearer ``` Löscht Datei und Metadaten-Eintrag. Nur eigene Dateien können gelöscht werden (sonst `404`). --- ## Erlaubte Dateitypen | Extension | MIME Type | | -------------- | --------------------------------------------------------------------------- | | `pdf` | `application/pdf` | | `txt` | `text/plain` | | `csv` | `text/csv` | | `jpg` / `jpeg` | `image/jpeg` | | `png` | `image/png` | | `gif` | `image/gif` | | `webp` | `image/webp` | | `doc` | `application/msword` | | `docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | | `xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | | `pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` | | `zip` | `application/zip` | | `mp4` | `video/mp4` | | `rdf` | `application/rdf+xml` | | `wav` | `audio/wav` | | `mp3` | `audio/mpeg` | | `ogg` | `audio/ogg` | | `json` | `application/json` | Der MIME-Typ wird server-seitig anhand der Datei-Magic-Bytes geprüft, nicht anhand des Client-Headers. --- ## Limits & Rate Limiting | Parameter | Wert | | --------------------------- | -------------------- | | Max. Dateien pro Request | 25 | | Max. Dateigröße | 200 MB | | Rate Limit Upload | 60 Requests / Minute | | Rate Limit Token-Erstellung | 10 Requests / Minute | --- ## Fehler | Code | Bedeutung | | ----- | ------------------------------------------------------------------------------------ | | `401` | Kein oder ungültiger Token | | `403` | Download gesperrt (`freigabe=false` oder `sperrfrist` in der Zukunft) | | `404` | Datei nicht gefunden oder gehört anderem Nutzer | | `422` | Validierungsfehler (Dateityp, Größe, ungültiger Pfad, ungültige Update-Felder/Werte) | | `429` | Rate Limit überschritten | **Beispiel Validierungsfehler** ```json { "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}/{path}/{filename} ``` Bei Namenskollision wird automatisch ein Suffix angehängt: ``` storage/app/private/uploads/1/projekte/2026/bericht_aB3xYz9k.pdf ```