95 lines
2.7 KiB
Markdown
95 lines
2.7 KiB
Markdown
# Multi-part File Upload API
|
|
|
|
This document outlines the process for uploading large files in chunks using the multi-part upload API.
|
|
|
|
## 1. Create an Upload Task
|
|
|
|
To begin a file upload, you first need to create an upload task. This is done by sending a `POST` request to the `/api/files/upload/create` endpoint.
|
|
|
|
**Endpoint:** `POST /api/files/upload/create`
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"hash": "string (file hash, e.g., MD5 or SHA256)",
|
|
"file_name": "string",
|
|
"file_size": "long (in bytes)",
|
|
"content_type": "string (e.g., 'image/jpeg')",
|
|
"pool_id": "string (GUID, optional)",
|
|
"bundle_id": "string (GUID, optional)",
|
|
"encrypt_password": "string (optional)",
|
|
"expired_at": "string (ISO 8601 format, optional)",
|
|
"chunk_size": "long (in bytes, optional, defaults to 5MB)"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
If a file with the same hash already exists, the server will return a `200 OK` with the following body:
|
|
|
|
```json
|
|
{
|
|
"file_exists": true,
|
|
"file": { ... (CloudFile object in snake_case) ... }
|
|
}
|
|
```
|
|
|
|
If the file does not exist, the server will return a `200 OK` with a task ID and chunk information:
|
|
|
|
```json
|
|
{
|
|
"file_exists": false,
|
|
"task_id": "string",
|
|
"chunk_size": "long",
|
|
"chunks_count": "int"
|
|
}
|
|
```
|
|
|
|
You will need the `task_id`, `chunk_size`, and `chunks_count` for the next steps.
|
|
|
|
## 2. Upload File Chunks
|
|
|
|
Once you have a `task_id`, you can start uploading the file in chunks. Each chunk is sent as a `POST` request with `multipart/form-data`.
|
|
|
|
**Endpoint:** `POST /api/files/upload/chunk/{taskId}/{chunkIndex}`
|
|
|
|
- `taskId`: The ID of the upload task from the previous step.
|
|
- `chunkIndex`: The 0-based index of the chunk you are uploading.
|
|
|
|
**Request Body:**
|
|
|
|
The body of the request should be `multipart/form-data` with a single form field named `chunk` containing the binary data for that chunk.
|
|
|
|
The size of each chunk should be equal to the `chunk_size` returned in the "Create Upload Task" step, except for the last chunk, which may be smaller.
|
|
|
|
**Response:**
|
|
|
|
A successful chunk upload will return a `200 OK` with an empty body.
|
|
|
|
You should upload all chunks from `0` to `chunks_count - 1`.
|
|
|
|
## 3. Complete the Upload
|
|
|
|
After all chunks have been successfully uploaded, you must send a final request to complete the upload process. This will merge all the chunks into a single file and process it.
|
|
|
|
**Endpoint:** `POST /api/files/upload/complete/{taskId}`
|
|
|
|
- `taskId`: The ID of the upload task.
|
|
|
|
**Request Body:**
|
|
|
|
The request body should be empty.
|
|
|
|
**Response:**
|
|
|
|
A successful request will return a `200 OK` with the `CloudFile` object for the newly uploaded file.
|
|
|
|
```json
|
|
{
|
|
... (CloudFile object) ...
|
|
}
|
|
```
|
|
|
|
If any chunks are missing or an error occurs during the merge process, the server will return a `400 Bad Request` with an error message.
|