Přeskočit na hlavní obsah

Files API

API reference pro endpointy správy souborů.

Přehled​

Files API poskytuje endpointy pro nahrávání, stahování a sdílení souborů uložených v Cloudflare R2.

Oprávnění: Většina endpointů vyžaduje autentizaci. Veřejný přístup k souborům používá tokeny.

Endpointy​

GET /files​

Seznam souborů s paginací a filtrováním.

Oprávnění: Bearer token (vyžaduje autentizaci)

Query parametry:

  • page (volitelné): Číslo stránky (výchozí: 1)
  • pageSize (volitelné): Počet položek na stránku (výchozí: 50, max: 100)
  • entity_type (volitelné): Filtrování podle typu entity (např. 'project')
  • entity_id (volitelné): Filtrování podle ID entity

Autorizace:

  • Sailor: Vidí pouze své vlastní soubory
  • Producer, Admin: Vidí všechny soubory

Response:

{
  "success": true,
  "data": {
    "files": [
      {
        "id": 1,
        "r2_key": "projects/123/files/1704067200000-abc123.pdf",
        "filename": "document.pdf",
        "mime_type": "application/pdf",
        "size": 1024000,
        "file_type": "FILE",
        "entity_type": "project",
        "entity_id": 123,
        "uploaded_by_user_id": 1,
        "public_token": null,
        "is_public": 0,
        "created_at": 1704067200
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "pageSize": 50,
      "totalPages": 1
    }
  }
}

POST /files/upload​

Nahrání souboru do R2 úložiště.

Oprávnění: Bearer token (vyžaduje autentizaci)

Request: Multipart form data

  • file (File): Soubor k nahrání
  • entity_type (volitelné, string): Typ entity (např. 'project', 'item')
  • entity_id (volitelné, number): ID entity
  • file_type (volitelné, string): Kategorie typu souboru ('FILE', 'PHOTO', 'OTHER')

Struktura R2 klíče:

  • Pro projekty: projects/{project_id}/files/{timestamp}-{random}.{ext} nebo projects/{project_id}/photos/{timestamp}-{random}.{ext}
  • Pro ostatní: {file_type}/{timestamp}-{random}.{ext}

Validace souboru:

  • Maximální velikost: 10MB
  • Povolené MIME typy:
    • Obrázky: image/jpeg, image/png, image/gif, image/webp
    • Dokumenty: application/pdf, text/plain, text/csv
    • Office: application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document
  • Povolené přípony: jpg, jpeg, png, gif, webp, pdf, txt, csv, xls, xlsx, doc, docx

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "r2_key": "other/1704067200000-abc123.pdf",
    "filename": "document.pdf",
    "mime_type": "application/pdf",
    "size": 1024000,
    "file_type": "OTHER",
    "entity_type": null,
    "entity_id": null,
    "uploaded_by_user_id": 1,
    "public_token": null,
    "is_public": 0,
    "created_at": 1704067200
  }
}

Error Response (soubor příliš velký):

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "File too large. Maximum size is 10MB"
}

Error Response (neplatný MIME typ):

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "File type application/x-executable is not allowed"
}

Rate Limit: 10 požadavků za minutu na uživatele

GET /files/:id/download​

Stažení souboru (autentizovaný přístup).

Oprávnění: Bearer token (vyžaduje autentizaci)

Response: Stream souboru s příslušnými hlavičkami

Headers:

  • Content-Type: MIME typ souboru
  • Content-Disposition: attachment; filename="filename.ext"

Error Response:

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "File not found"
}

PUT /files/:id/public​

Vygenerování veřejného sdílecího tokenu pro soubor.

Oprávnění: Bearer token (vyžaduje autentizaci, vlastník nebo Admin)

Request: Žádný

Response:

{
  "success": true,
  "data": {
    "file_id": 1,
    "public_token": "base64url-43-character-token",
    "public_url": "/files/public/base64url-43-character-token",
    "message": "File is now publicly accessible"
  }
}

Error Response (není vlastník):

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "You do not have permission to share this file"
}

Rate Limit: 2000 požadavků za minutu na uživatele

DELETE /files/:id/public​

Zrušení veřejného sdílení souboru.

Oprávnění: Bearer token (vyžaduje autentizaci, vlastník nebo Admin)

Request: Žádný

Response:

{
  "success": true,
  "data": {
    "file_id": 1,
    "message": "Public sharing revoked"
  }
}

Rate Limit: 2000 požadavků za minutu na uživatele

GET /files/public/:token​

Stažení souboru pomocí veřejného tokenu (autentizace není vyžadována).

Oprávnění: Žádné (veřejný endpoint)

Response: Stream souboru s příslušnými hlavičkami

Headers:

  • Content-Type: MIME typ souboru
  • Content-Disposition: attachment; filename="filename.ext"

Error Response:

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "File not found or not publicly accessible"
}

Bezpečnost souborů​

Sanitizace názvu souboru​

Názvy souborů jsou sanitizovány, aby se zabránilo:

  • Path traversal útokům (../, ..\\)
  • Null bytům
  • Vedoucím/koncovým tečkám a mezerám
  • Řídicím znakům
  • Délka omezena na 255 znaků

Generování R2 klíče​

R2 klíče jsou generovány bezpečně:

  • Formát: {file_type}/{timestamp}-{random}.{extension}
  • Žádný uživatelský vstup při generování klíče
  • Zabraňuje kolizím a path traversal

Bezpečnost veřejného tokenu​

  • Délka: 43 znaků (32 bytů base64url-encoded)
  • Jedinečnost: Kontrolována proti databázi před přiřazením
  • Generování: Kryptograficky bezpečný náhodný (crypto.getRandomValues)
  • Zrušení: Může být zrušeno vlastníkem nebo Adminem

Typy souborů​

Běžné kategorie typů souborů:

  • FILE - Dokumenty a soubory (PDF, Word, Excel, atd.)
  • PHOTO - Obrázkové soubory (fotky)
  • OTHER - Ostatní typy souborů

Struktura složek​

Soubory jsou organizovány ve struktuře složek v R2:

Pro projekty:

  • projects/{project_id}/files/ - Dokumenty projektu
  • projects/{project_id}/photos/ - Fotky projektu

Pro ostatní:

  • {file_type}/ - Obecné soubory podle typu

Tato struktura umožňuje snadné filtrování a správu souborů podle projektu.

Kódy chyb​

  • VALIDATION_ERROR - Neplatný vstup (velikost souboru, MIME typ, přípona)
  • NOT_FOUND - Soubor nenalezen
  • FORBIDDEN - Nedostatečná oprávnění
  • INTERNAL_ERROR - Chyba serveru

Související témata​