BOS (Baidu Object Storage) is a stable, secure, efficient and highly scalable storage service provided by Baidu AI Cloud, which supports any type of data storage, such as text, multimedia, and binary data. The data is stored in multiple regions and across clusters to realize the unified utilization of resources, reduce the use difficulty, and improve the work efficiency. Users can manage the resources and upload/download the data through the simple RESTful API provided in this document.

API3.0 Introduction

Baidu AI Cloud API upgrades to API3.0, which provides the visual API debugging interface and can automatically generate the code required for API call, to help developers for more efficient R&D and testing. At present, API3.0 supports BOS, EIP and DTS. Please look forward to more products. It supports more product access in future.

At present, API3.0 is in the Open Beta Test stage. If you have any suggestion on the API3.0 documentation, debugging interface and code sample, you can give feedback through the documentation feedback entry.

Service Field Name

Baidu AI Cloud provides the multi-region support. For the regions supported by BOS and corresponding domain names, see [Get Access Domain Name](https://cloud.baidu.com/doc/BOS/s/Ck1rk80hn#Get Access Domain Name).

Normalized String (UrlEncode)

Generally, a string contains any Unicode character. This flexibility can bring a lot of a hassle in programming. Hence the concept of "canonical strings” is introduced. A specification string contains only percent coded Characters and URI (Uniform Resource Identifier) non-reserved Characters. RFC 3986 specifies that non-reserved URI characters include the following: letters (S-z, a-z), digits (0-9), hyphens (-), dot (.), underscores (_), tilde (~) The way to convert any string to a canonical string is:

• Converts the string to the byte string coded by UTF-8.
• Leave all URI non-reserved characters as the same.
• Perform Percent-Encoding on the rest of the bytes according to RFC 3986, that means a % is followed by two hexadecimal letters representing the byte value. All letters are capitalized. Example: The original string:this is an example for test, the corresponding normal string:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

Notes: The following sample code takes Java as an example to demonstrate how to realize UrlEncode. The input is the input string, and encodeSlash is used to control whether "/" is encoded. In some cases, you need to ignore "/" during UrlEncode. For more information, see Coding Specifications.

public static String uri-encode(CharSequence input, boolean encodeSlash) {
    StringBuilder result = new StringBuilder();
    for (int i = 0; i < input.length(); i++) {
    char ch = input.charAt(i);
    if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' || ch == '-' || ch == '~' || ch == '.') {
        result.append(ch);
        } else if (ch == '/') {
            result.append(encodeSlash ? "%2F" : ch);
        } else {
            result.append(toHexUTF8(ch));
        }
    }
    return result.toString();
}

Encoding Specification

• Resolvable content, and UTF-8 encoding is adopted for all request/response body contents at present. More encoding types will be supported later.

• When requesting, UrlEncode is required for the following:

  • Objectname, where "/" needs to be ignored when Resource is doing URLEncode.
  • Value of querystring.
  • x-bce-copy-source
  • Custom Meta:Meta Value only supports visible ASCII characters. If other characters are needed, UrlEncode processing is recommended.

Request Syntax Style

The request syntax of the BOS API can be the style without “/v{version}/” and compatible with the style with “/v{version}/”. Taking GetObject as an example, the API call methods in the following two styles are correct.

• Request syntax without /v{version}/: GET /object HTTP/1.1
• Request syntax with /v{version}/: GET /v1/bucket/object HTTP/1.1

Number and Size Specification of Resources

• Users can possess 100 buckets. If you need more buckets, you can apply for them through the ticket system.
• The number of objects in a bucket is not limited.
• The maximum size of a single object can be 5 TB.
• The size of the user request header should not exceed 8 KB. The user-defined meta (x-bce-meta-) should not exceed 2 KB. The meta value cannot be null and can be in the ASCII format only.

Naming Conventions

Bucket format requirements:

• It can only contain lowercase letters, numbers and hyphen ("-").
• The bucket name must start and end with lowercase letters or numbers.
• The length is 3-63 bits.

Object format requirements: The length cannot exceed 1024 bytes of UTF-8 characters.

Date and Time

Date and time can be represented in many ways. For unification, unless it is established by convention or has corresponding specifications, all the date and time fields specified in the HTTP standard are expressed in GMT, and all other date and time fields are expressed in UTC time, following ISO 8601 and subject to the following restrictions:

• All dates should adopt the form ofYYYY-MM-DD, for example,2014-06-01is represented as 1 June, 2014.
• All time should adopt the form ofhh:mm:ssand add a capital Z at the end to indicate UTC time. For example,23:00:10Zindicates that UTC time is 23:0:10
• As to the combination of date and time, add the letter T between the two. For example2014-06-01T23:00:10Zindicate UTC time is 23:0:10 on 1 June, 2014.