File uploading

August 15, 2024 ยท View on GitHub

Table of Contents

Drivers support

Out-of-box we support the following drivers: local, s3, and s3-presigned. You can set it in the .env file, variable FILE_DRIVER. If you want to use another service for storing files, you can extend it.

For production we recommend using the "s3-presigned" driver to offload your server.

Uploading and attach file flow for local driver

Endpoint /api/v1/files/upload is used for uploading files, which returns File entity with id and path. After receiving File entity you can attach this to another entity.

An example of uploading an avatar to a user profile (local)

sequenceDiagram
    participant A as Fronted App
    participant B as Backend App

    A->>B: Upload file via POST /api/v1/files/upload
    B->>A: Receive File entity with "id" and "path" properties
    note left of A: Attach File entity to User entity
    A->>B: Update user via PATCH /api/v1/auth/me

Video example

https://user-images.githubusercontent.com/6001723/224558636-d22480e4-f70a-4789-b6fc-6ea343685dc7.mp4

Uploading and attach file flow for s3 driver

Endpoint /api/v1/files/upload is used for uploading files, which returns File entity with id and path. After receiving File entity you can attach this to another entity.

Configuration for s3 driver

  1. Open https://s3.console.aws.amazon.com/s3/buckets

  2. Click "Create bucket"

  3. Create bucket (for example, your-unique-bucket-name)

  4. Open your bucket

  5. Click "Permissions" tab

  6. Find "Cross-origin resource sharing (CORS)" section

  7. Click "Edit"

  8. Paste the following configuration

    [
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

  9. Click "Save changes"

  10. Update .env file with the following variables:

    FILE_DRIVER=s3
ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
AWS_S3_REGION=YOUR_AWS_S3_REGION
AWS_DEFAULT_S3_BUCKET=YOUR_AWS_DEFAULT_S3_BUCKET

An example of uploading an avatar to a user profile (S3)

sequenceDiagram
    participant A as Fronted App
    participant B as Backend App
    participant C as AWS S3

    A->>B: Upload file via POST /api/v1/files/upload
    B->>C: Upload file to S3
    B->>A: Receive File entity with "id" and "path" properties
    note left of A: Attach File entity to User entity
    A->>B: Update user via PATCH /api/v1/auth/me

Uploading and attach file flow for s3-presigned driver

Endpoint /api/v1/files/upload is used for uploading files. In this case /api/v1/files/upload receives only fileName property (without binary file), and returns the presigned URL and File entity with id and path. After receiving the presigned URL and File entity you need to upload your file to the presigned URL and after that attach File to another entity.

Configuration for s3-presigned driver

  1. Open https://s3.console.aws.amazon.com/s3/buckets

  2. Click "Create bucket"

  3. Create bucket (for example, your-unique-bucket-name)

  4. Open your bucket

  5. Click "Permissions" tab

  6. Find "Cross-origin resource sharing (CORS)" section

  7. Click "Edit"

  8. Paste the following configuration

    [
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": []
  }
]

    For production we recommend to use more strict configuration:

    [
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["PUT"],
    "AllowedOrigins": ["https://your-domain.com"],
    "ExposeHeaders": []
  },
   {
     "AllowedHeaders": ["*"],
     "AllowedMethods": ["GET"],
     "AllowedOrigins": ["*"],
     "ExposeHeaders": []
   }
]

  9. Click "Save changes"

  10. Update .env file with the following variables:

    FILE_DRIVER=s3-presigned
ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
AWS_S3_REGION=YOUR_AWS_S3_REGION
AWS_DEFAULT_S3_BUCKET=YOUR_AWS_DEFAULT_S3_BUCKET

An example of uploading an avatar to a user profile (S3 Presigned URL)

sequenceDiagram
    participant C as AWS S3
    participant A as Fronted App
    
    participant B as Backend App

    A->>B: Send file name (not binary file) via POST /api/v1/files/upload
    note right of B: Generate presigned URL
    B->>A: Receive presigned URL and File entity with "id" and "path" properties
    A->>C: Upload file to S3 via presigned URL
    note right of A: Attach File entity to User entity
    A->>B: Update user via PATCH /api/v1/auth/me

How to delete files?

We prefer not to delete files, as this may have negative experience during restoring data. Also for this reason we also use Soft-Delete approach in database. However, if you need to delete files you can create your own handler, cronjob, etc.

Previous: Serialization

Next: Tests