# Migrate from v1/v2

Compared with v1/v2, CloudDisk v3 has the following advantages:

- Closer to the API style of popular cloud storage
- Faster response and lower performance consumption
- Simpler and more friendly operations on console
- More features
- SDK for JAVA, and more languages can be supported if you request them

## Compare Features

|                        | v3                                                                                       | v2                                                                                      |
| ---------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| ***Bucket***           |      -                                                                                    |     -                                                                                    |
| Online Management      | ✓                                                                                        | ✓                                                                                       |
| Cross-env Management   | ✓                                                                                        | ✗                                                                                      |
| Non-prod Testing       | ✓                                                                                        | ✗                                                                                      |
| Support Storage        | AWS S3<br/>OCI storage<br/>Minio<br/>S3 Compatible<br/>Azure Blob Storage<br/>Aliyun OSS | AWS S3<br/>S3 Compatible<br/>Azure Blob Storage<br/>Aliyun OSS<br/>Microsoft Sharepoint |
| ***Object***           |     -                                                                                     |         -                                                                                |
| Online Management      | Full                                                                                     | Only Top 200 Objects                                                                    |
| Basic Actions          | LIST/GET/PUT/DELETE                                                                      | LIST/GET/PUT/DELETE                                                                     |
| Upload Limit           | Up to 200MB per upload request, see [Quota Standards](../InsureMO_Foundation_Quota_Standards.md) | 20MB                                                                                    |
| Object Headers         | ✓                                                                                        | ✗                                                                                      |
| Object Metadata        | ✓                                                                                        | ✗                                                                                      |
| Object Tags            | ✓                                                                                        | ✗                                                                                      |
| Multipart Upload       | ✓                                                                                        | Only no-trace mode                                                                      |
| Pre-sign Object        | ✓                                                                                        | ✓                                                                                       |
| Get with Preconditions | ✓                                                                                        | ✗                                                                                      |
| Download Part          | ✓                                                                                        | ✗                                                                                      |
| ***Development***      |    -                                                                                      |       -                                                                                  |
| Upload Format          | Stream/Binary                                                                            | Base64-String                                                                           |
| insureMO SDK For JAVA  | ✓                                                                                        | ✗                                                                                      |


## Compare API

<table>
<tr><th rowspan="2" colspan="2">Action</th><th colspan="5">API    {{gateway}}/mo-fo/1.0/…</th></tr>
<tr><th colspan="2">v3</th><th colspan="2">v2</th><th>New Features in v3</th></tr>
<tr><td rowspan="5">Bucket</td><td>Create Bucket</td><td>POST</td><td>/clouddisk/v3/bucket/add-one</td><td>POST</td><td>/clouddiskv2/bucket/create</td><td rowspan="5">- Support more options, such as object prefix.<br>- Support default mode(for some env).<br>- Add audit logs for all actions.<br>- Different api response format.<br>- Java SDK</td></tr>
<tr><td>List Bucket</td><td>GET</td><td>/clouddisk/v3/bucket/query-many</td><td>GET</td><td>/clouddiskv2/bucket/list</td></tr>
<tr><td>Delete Bucket</td><td>POST</td><td>/clouddisk/v3/bucket/delete-one</td><td>POST</td><td>/clouddiskv2/bucket/delete</td></tr>
<tr><td>Update Bucket</td><td>POST</td><td>/clouddisk/v3/bucket/update-one</td><td>POST</td><td>/clouddiskv2/bucket/config/update</td></tr>
<tr><td>Get a Bucket</td><td>GET</td><td>/clouddisk/v3/bucket/query-one</td><td>GET</td><td>/clouddiskv2/bucket/get</td></tr>
<tr><td rowspan="15">Object</td><td>Put Object</td><td>POST</td><td>/clouddisk/v3/object/put</td><td>POST</td><td>/clouddiskv2/object/putobject</td><td>object content as request body, stream upload</td></tr>
<tr><td>Get Object</td><td>GET</td><td>/clouddisk/v3/object/get</td><td>GET</td><td>/clouddiskv2/object/getobject</td><td>object content as response body, stream download</td></tr>
<tr><td>List Objects</td><td>GET</td><td>/clouddisk/v3/object/list</td><td>POST</td><td>/clouddiskv2/object/list</td><td>list more objects by continue token</td></tr>
<tr><td>Delete Object</td><td>POST</td><td>/clouddisk/v3/object/delete</td><td>POST</td><td>/clouddiskv2/object/delete</td><td> - </td></tr>
<tr><td>Delete Objects</td><td>POST</td><td>/clouddisk/v3/object/delete/many</td><td> - </td><td> - </td><td>New Features</td></tr>
<tr><td>Exist Object</td><td>GET</td><td>/clouddisk/v3/object/exist</td><td>POST</td><td>/clouddiskv2/object/exist</td><td> - </td></tr>
<tr><td>Get Object Metadata</td><td>GET</td><td>/clouddisk/v3/object/metadata/get</td><td> - </td><td> - </td><td>New Features</td></tr>
<tr><td>Create Multipart Upload</td><td>POST</td><td>/clouddisk/v3/object/put/multipart/create</td><td>POST</td><td>/clouddiskv2/object/put/multipart/start</td><td> - </td></tr>
<tr><td>Upload part</td><td>POST</td><td>/clouddisk/v3/object/put/multipart/upload</td><td>POST</td><td>/clouddiskv2/object/put/multipart/upload</td><td> - </td></tr>
<tr><td>Complete Multipart Upload</td><td>POST</td><td>/clouddisk/v3/object/put/multipart/complete</td><td>POST</td><td>/clouddiskv2/object/put/multipart/complete</td><td> - </td></tr>
<tr><td>Abort Multipart Upload</td><td>POST</td><td>/clouddisk/v3/object/put/multipart/abort</td><td>POST</td><td>/clouddiskv2/object/put/multipart/abort</td><td> - </td></tr>
<tr><td>Presign/Share Object</td><td>POST</td><td>/clouddisk/v3/object/presign</td><td>POST</td><td>/clouddiskv2/object/share</td><td> - </td></tr>
<tr><td>Put Object Tags</td><td>POST</td><td>/clouddisk/v3/object/tag/put</td><td> - </td><td> - </td><td>New Features</td></tr>
<tr><td>Get Object Tags</td><td>GET</td><td>/clouddisk/v3/object/tag/get</td><td> - </td><td> - </td><td>New Features</td></tr>
<tr><td>Delete Object Tags</td><td>POST</td><td>/clouddisk/v3/object/tag/delete</td><td> - </td><td> - </td><td>New Features</td></tr>
</table>

## Migration

If you use the v2 version of the API with `no_trace` mode, you can directly configure the new version of bucket and use it.

### FAQ

<details>
<summary>Can a v2 bucket be migrated to a v3 bucket?</summary>

Yes. What you migrate is the CloudDisk **bucket definition**, not the bucket on the cloud storage behind it — the cloud bucket itself stays untouched. You re-create the bucket in v3 pointing at the same storage target, and the objects already stored there remain accessible.

Note that a v3 bucket name must be 6 to 63 characters long, must begin with a letter, and must not start with `mo-`. See [Naming a Bucket](./InsureMO_clouddisk_bucket#naming-a-bucket) for the full rules. If your current v2 bucket name does not satisfy them, you have to rename the bucket — and update every place the old name is hard-coded in your code.

</details>
<details>
<summary>Do I need to migrate existing objects?</summary>

It depends on how your v2 bucket was accessed.

- **`no_trace` mode**: no object migration is needed. The keys in the storage target already match the keys you pass in, so you only need to create the v3 bucket and update your code. Make sure the `source_prefix` of the new bucket matches the prefix v2 used, otherwise the keys will not line up.
- **Normal mode**: object migration is required. In normal mode, CloudDisk rewrites the key before storing it (tenant and bucket as the prefix, version as the suffix) and keeps a record of the object on the CloudDisk side. v3 stores an object under the key exactly as given. A migration job is provided to rename the existing objects and register them; contact your insureMO support contact for the procedure.

</details>
<details>
<summary>What has to change in my code?</summary>

The transport format is the biggest change:

- *Put Object* takes the object as the **binary request body** instead of a Base64 string, and *Get Object* returns the object as the **response body** instead of Base64 inside a JSON payload.
- All JSON responses are wrapped as `{"code": ..., "message": ..., "trace_id": ..., "data": ...}`.
- *List Objects* is now a `GET` with query parameters and pages through `continuation_token`. *Exist Object* is now a `GET`.
- Endpoints move from `/clouddiskv2/…` to `/clouddisk/v3/…`. See [Compare API](#compare-api) for the full mapping.

To scope the work on your side, search your codebase for `clouddiskv2`, `putobject` / `getobject`, `object/share`, Base64 encoding and decoding around CloudDisk calls, and any hard-coded bucket names.

</details>
<details>
<summary>Can v2 and v3 run in parallel?</summary>

Yes. You can leave existing data and configuration on v2 while writing new data through a v3 bucket, which means no object migration is needed.

If you do this, do not let v2 and v3 write to the same prefix in the same storage target. In normal mode v2 rewrites keys while v3 does not, so the same file would end up stored under two different keys.

</details>