API for Object Storage / S3 Buckets in China

1. Authentication

There are two possible options for the authentication: Basic Authentication with username and password or Signature Verification for improved security.

1.1. Basic Authentication

Basic Authentication requires your username and password, which are sent as a Base64 encoded string in the Authorization header.

Example 1

curl -u <username>:<password> https://<s3.webercloud-china.cn>/<bucket>/

Example 2

curl -X GET \
    https://<s3.webercloud-china.cn>/<bucket>/ \
    -H "Authorization: Basic <Base64(username:password)>"

1.2. Signature Verification

In addition to your username and password, the Signature Verification also includes the HTTP method, the URI, the date and optionally the content of the file. Signature Verification provides better security, but a new signature needs to be calculated for each request.

A signature can be calculated in the following way:

Base64(HMAC-SHA1(<password>,<method>&<uri>&<date>&<content-md5>))

Related parameter description

• Password: The password related to your username.
• Method: The corresponding HTTP method, such as GET, POST, PUT and HEAD.
• URI: The request path in the format /bucket/URI.
• Date: Request date and time, such as Wed, 22 Apr 2020 02:26:58 GMT or 2020-04-22 10:26:58.
• Content-MD5 (optional): MD5 value of the request body. If the file is too large to calculate MD5 or the request body is empty, it can be empty.

Additional notes

• MD5 hashes should be encoded as 32 lowercase hexadecimal digits.
• The output of HMAC-SHA1 must be raw binary data.
• Date is used to verify whether the signature is valid. The validity period of a signature is 30 minutes.

Example

curl -X PUT \
    https://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "Authorization: WESTYUN <username>:<signature>" \
    -H "Content-MD5: <7ac66c0f148de9519b8bd264312c4d64>" \
    -H "Date: <2020-04-23 16:24:46>" \
    -H "Content-Type: <image/jpeg>" \
    -H "Content-Length: <33456>"

2. REST API

2.1. Upload files

PUT /<bucket>/<path_to_file>

Request headers

Additional notes

• The maximum supported single-thread file upload size is 1 GB. For files larger than 1 GB, you need to upload the file in chunks. It is generally recommended to upload the file in chunks if it is larger than 100 MB.
• Storing a large number of files in the same directory at the same time may affect performance, so it is recommended that when there are too many files, they are stored in different subdirectories.

Content-Secret parameter

If a content secret is set for a file, it cannot be accessed directly anymore. Any requests to the file need to include the content secret, which needs to be added at the end of the URL, separated with "!". Example: https://<s3.webercloud-china.cn>/<bucket>/<path_to_secret_file>!<content-secret>

To delete or modify a content-secret, see Metadata.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.2. Upload files in chunks

PUT /<bucket>/<path_to_file>

Initialization request headers

Chunk upload request headers

Finalize upload request headers

Additional notes

• The maximum supported file size is 13 TB.
• Except for the last chunk, all chunks need to have a size of exactly 1 MB.
• In order to upload a file in chunks, the upload needs to be initialized first.
• After initialization is completed, blocks can be uploaded in parallel.
• Once all chunks have been uploaded, the upload needs to be finalized.
• The file will not be available on the bucket before all chunks have been uploaded, or if the upload is never finalized.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example

Initialization:

curl -X PUT \
    http://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "x-west-multi-disorder:true" \
    -H "x-west-multi-stage:initiate" \
    -H "x-west-multi-length:<2097162>" \
    -H "x-west-multi-type:<image/jpg>" \
    -H "Authorization: Basic <Base64(username:password)>"

Upload of chunks:

curl -X PUT \
    http://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "x-west-multi-disorder:true" \
    -H "x-west-multi-stage:upload" \
    -H "x-west-part-id:0" \
    -H "Authorization: Basic <Base64(username:password)>"
    -d <1 MB payload>

curl -X PUT \
    http://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "x-west-multi-disorder:true" \
    -H "x-west-multi-stage:upload" \
    -H "x-west-part-id:1" \
    -H "Authorization: Basic <Base64(username:password)>"
    -d <1 MB payload>

curl -X PUT \
    http://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "x-west-multi-disorder:true" \
    -H "x-west-multi-stage:upload" \
    -H "x-west-part-id:2" \
    -H "Authorization: Basic <Base64(username:password)>"
    -d <remaining payload>

Finalize upload:

curl -X PUT \
    http://<s3.webercloud-china.cn>/<bucket>/<image.jpg> \
    -H "x-west-multi-disorder:true" \
    -H "x-west-multi-stage:complete" \
    -H "Authorization: Basic <Base64(username:password)>"

2.3. Copy files

PUT /<bucket>/<new_path_to_file>

Request headers

Additional notes

• You can only copy files within the same bucket.
• Directories cannot be copied.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.4. Move files

PUT /<bucket>/<new_path_to_file>

Request headers

Additional notes

• You can only copy files within the same bucket.
• Copying directories is not supported

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.5. Download files

GET /<bucket>/<path_to_file>

Request headers

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.6. Deleting files

DELETE /<bucket>/<path_to_file>

Request headers

Additional notes

• A frequency limit may be imposed on synchronous deletion requests. If you need to delete a large number of files, asynchronous is recommended.
• For asynchronous deletions, the request will return the status code 200 immediately, even though the file may not be deleted yet.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.7. Get file information

HEAD /<bucket>/<path_to_file>

Response

• Upon success, the status code 200 will be returned. The response also includes the response headers listed below.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.8. Modify file metadata

PATCH /<bucket>/<path_to_file>?metadata=<option>

Options

Request headers

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.9. Create a directory

POST /<bucket>/<path_to_directory>

Request headers

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.10. Delete a directory

DELETE /<bucket>/<path_to_directory>

Additional notes

• Only empty directories are allowed to be deleted.
• If there are still files in the directory, the deletion request will fail. You need to delete all files in the directory first, before you can delete the directory.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

2.11. Get a list of files within a directory

GET /<bucket>/<path_to_directory>

Request headers

Additional notes

• If the number of files in a directory exceed the value of x-list-limit, the files will be seperated into multiple pages and the response will only include the first page as well as the name of the iterator for the next page.
• In order to receive the next page, another request needs to be sent and this request needs to include the name of the iterator that was received in the previous request.
• The name of the iterators are based on Base64-encoded random numbers. If the name of the iterator is "bmV4dCBpbmRleDpFT0Y=", it indicates the last page. 

Response

• Upon success, the status code 200 will be returned. The response also includes the list of files in a JSON format.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

3. S3 API

The S3 API is based on the REST API and provides additional options and parameters to make it as compatible with the S3 API from AWS as possible.

3.1. Compatibility overview

• S3 API supports file-related API calls.
• Region-related configuration is not supported.
• Authentication is compatible with both AWS Signature Version 2 and AWS Signature Version 4.
• You need to use the username as AccessKey and the password as SecretAccessKey.

Common request headers

Common response headers

3.2. Upload files

PUT /<bucket>/<path_to_file>

Additional request headers

Additional notes

• The maximum supported single-thread file upload size is 1 GB. For files larger than 1 GB, you need to upload the file in chunks. It is generally recommended to upload the file in chunks if it is larger than 100 MB.
• Storing a large number of files in the same directory at the same time may affect performance, so it is recommended that when there are too many files, they are stored in different subdirectories.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example

PUT /<bucket>/<test.txt> HTTP/1.1
Host: <s3.webercloud-china.cn>
Date: <Mon, 11 Jul 2023 03:20:29 GMT>
Authorization: <authorization string>
Content-Type: text/plain
Content-Length: <1314>

3.3. Upload files in chunks

Initialization

Initialize the upload in chunks and obtain the globally unique UploadId. Subsequent requests for the upload in chunks require the UploadId as a request parameter.

Request:

Example:

POST /<bucket>/<test.txt>?uploads HTTP/1.1
Host: <s3.webercloud-china.cn>
Date: <Mon, 11 Jul 2023 03:20:29 GMT>
Authorization: <authorization string>
x-west-multi-length: <1134000>

Response:

The response only includes common response headers, and provides additional information as XML in the request body.

Example:

HTTP/1.1 200 OK
<?xml version = "1.0" encoding = "UTF-8" ?>
<InitiateMultipartUploadResult xmlns = "http://s3.amazonaws.com/doc/2006-03-01/" >
    <Bucket><bucket></Bucket>
    <Key><test.txt></Key>
    <UploadId>e3868700-018b-41a3-8a9a-e093b7a22fc4</UploadId>
</InitiateMultipartUploadResult>

Chunk upload

Request:

The request uses only common request headers. Additional parameters must be added as GET parameters to the URL.

Example:

PUT /<bucket>/<test.txt>?partNumber=<PartNumber>&uploadId=<UploadId> HTTP/1.1 
Host: <s3.webercloud-china.cn>
Date: <Mon, 11 Jul 2023 03:20:29 GMT>
Content-Length: <1134000>
Authorization: <authorization string>

Response:

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example:

HTTP/1.1 200 OK
x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97
Date: <Wed, 12 Oct 2023 17:51:00 GMT>
ETag: "b54357faf0632cce46e942fa68356b38" 
Content-Length: 0
Connection: keep-alive

Finalize upload

Request:

The request uses only common request headers. Additional parameters must be added as GET parameters to the URL.

Additionally, the payload needs to include an XML with all parts and their corresponding ETag.

Example:

POST /<bucket>/<test.txt>?uploadId=<UploadId> HTTP/1.1 
Host: <s3.webercloud-china.cn>
Date: <Mon, 11 Jul 2023 03:20:29 GMT>
Content-Length: <1134000>
Authorization: <authorization string>
​
<CompleteMultipartUpload>
    <Part>
        <PartNumber>1</PartNumber>
        <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
    </Part>
    <Part>
        <PartNumber>2</PartNumber>
        <ETag>"0c78aef83f66abc1fale8477f296d394"</ETag>
    </Part>
    <Part>
        <PartNumber>3</PartNumber>
        <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
    </Part>
    ...
</CompleteMultipartUpload>

Response:

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example:

HTTP/1.1 200 OK 
x-amz-request-id: 3141cdab-1387-4872-b6e7-e83ec0f9fc97 
Date: Wed, 12 Oct 2023 17:50:00 GMT 
Connection: close 
​
<?xml version="1.” encoding="UTF-8"?>
<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Location>https://<s3.webercloud-china.cn>/<bucket>/<test.txt></Location>
    <Bucket><bucket></Bucket>
    <Key><test.txt></Key>
    <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
</CompleteMultipartUploadResult>

Additional notes

• Except for the last chunk, all chunks need to have a size of exactly 1 MB.
• In order to upload a file in chunks, the upload needs to be initialized first.
• After initialization is completed, blocks can be uploaded in parallel.
• Once all chunks have been uploaded, the upload needs to be finalized.

3.4. Copy files

PUT /<bucket>/<new_path_to_file>

Additional request headers

Additional notes

• You can only copy files within the same bucket.
• Directories cannot be copied.

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example

PUT /<bucket>/<test.txt> HTTP/1.1
Host: <s3.webercloud-china.cn>
Date: <Wed, 12 Oct 2023 17:50:00 GMT>
x-amz-copy-source: /<bucket>/<copy.txt>
Authorization: <authorization string>
​
HTTP/1.1 200 OK
x-amz-request-id: 3141cdab-1337-4872-b6e7-e83ec0f9fc97
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: close
​
<CopyObjectResult>
    <LastModified>2023-10-12T17:50:30.000Z</LastModified>
    <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
</CopyObjectResult>

3.5. Download files

GET /<bucket>/<path_to_file>

Request headers

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

3.6. Deleting files

DELETE /<bucket>/<path_to_file>

Response

• Upon success, the status code 200 will be returned.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

3.7. Get file information

HEAD /<bucket>/<path_to_file>

Response

• Upon success, the status code 200 will be returned. The response also includes the response headers listed below.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

3.8. Get a list of files within a directory

GET /<bucket>/<path_to_directory>?list-type=2

Request

The request uses only common request headers. Additional parameters must be added as GET parameters to the URL.

Response

• Upon success, the status code 200 will be returned. The response also includes the list of files in an XML format.
• If failed, an error message will be returned. Please refer to the API Error Code Table for details.

Example

GET /<bucket>/?list-type = 2 HTTP/1.1
Host: <s3.webercloud-china.cn>
X-Amz-Date: <20230628T063714Z>
Authorization: <authorization string>
Content-Type: text/plain
​
HTTP/1.1 200 OK
<?xml version = "1.0" encoding = "UTF-8" ?>
<ListBucketResult xmlns = "http://fss-my.vhostgo.com/doc/2006-03-01/" >
    <Name><bucket></Name>
    <Prefix/>
    <KeyCount>205</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>test.txt</Key>
        <LastModified>2022-10-12T17:50:30.0Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        ...
    </Contents>
    ...
</ListBucketResult>

4. API Error Code Table

When an API request fails, the server will return a response body in JSON format. It can be used to locate the specific cause of the error. For example:

{"msg":"authorization error","code":401000002,"id":"238235e6-8160-48ed-a9b2-1309938b09a9"}

This JSON response includes the following information:

• msg: A brief description of the error.
• id: A unique ID related to this request.
• code: The error code. For specific meanings, refer to the table below.