file-uploading.md

File uploading

---

Table of Contents

• Drivers support
• Uploading and attach file flow for local driver
  • An example of uploading an avatar to a user profile (local)
  • Video example
• Uploading and attach file flow for s3 driver
  • Configuration for s3 driver
  • An example of uploading an avatar to a user profile (S3)
• Uploading and attach file flow for s3-presigned driver
  • Configuration for s3-presigned driver
  • An example of uploading an avatar to a user profile (S3 Presigned URL)
• How to delete files?

---

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

Loading

Video example

file-uploading.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

Loading

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

Loading

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