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 work efficiency. Users can manage the resources and upload/download the data through the simple RESTful API provided in this document.

If you first call the API of Baidu AI Cloud products, watch Video Guide for API Getting Started and master the method for API Calling quickly.

Service Field Name

Baidu AI Cloud provides 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 trouble in programming. Hence the concept of "canonical strings” is introduced. A specification string contains percent coded Characters and URI (Uniform Resource Identifier) non-reserved Characters only. 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, which 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

Descriptions: The following sample code takes Java as an example to demonstrate how to implement 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 Encoding 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 all request/response body contents are UTF-8 encoded at present. More encoding types will be supported later.

• When you make a request, 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

The bucket format requirements are as follows:

• It can only contain lowercase letters, numbers, and hyphens ("-").
• 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 be in the form of YYYY-MM-DD, e.g., 2014-06-01 is represented as 1 June 2014.
• All times should be in the form of hh:mm:ss and add a capital Z at the end to indicate the UTC time. For example, 23:00:10Z indicates that the UTC time is 23:0:10
• As to the combination of date and time, add the letter T between the two parts. For example, 2014-06-01T23:00:10Z indicates that the UTC time is 23:0:10 on 1 June 2014.