Overview

Baidu AI Cloud Object Storage (BOS) is a highly stable, secure, efficient, and scalable public storage service provided by Baidu AI Cloud. It supports various data types such as text, multimedia, and binary. Multi-region storage across clusters ensures unified resource utilization, simplifies use, and boosts work efficiency. Users can manage resources and upload/download data using the straightforward RESTful API described in this document.

Introduction to API 3.0

Baidu AI Cloud API has been upgraded to API 3.0, which provides a visual API debugging interface and can automatically generate the code required for calling APIs, helping developers carry out R&D and test more efficiently. API 3.0 now supports products such as Baidu AI Cloud Object Storage (BOS), Elastic IP (EIP) and Data Transmission Service (DTS). More products are being integrated, so stay tuned.

API 3.0 is currently in public beta. If you have feedback about the documentation, debugging interface, code samples, or other components of API 3.0, you can submit it via the document feedback portal.

Service domain

Baidu AI Cloud has opened multiple regions. For regions supported by BOS and corresponding domain names, please refer to Get the Endpoint.

Normalized string (urlEncode)

A string can usually contain any Unicode character. This flexibility can cause many troubles in programming. Therefore, the concept of “normalized string” is introduced. A normalized string contains only percent-encoded characters and URI (Uniform Resource Identifier) unreserved characters. RFC 3986 stipulates that URI unreserved characters include the following: letters (A-Z, a-z), numbers (0-9), hyphens (-), dots (.), underscores (_), and tildes (~). The way to convert any string into a normalized string is:

• Convert the string into a UTF-8 encoded byte stream.
• Leave all unreserved URI characters unchanged.
• Perform percent-encoding as specified in RFC 3986 on the remaining bytes, i.e., a % followed by two hexadecimal letters representing the byte value. Letters are in uppercase. Example: Original string: this is an example for testing, Corresponding normalized string: this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95.

Notes The following example code uses java as an example to demonstrate how to perform UrlEncode. Among them, input is the input string, and encodeSlash is used to control whether to encode "/". In some cases, it is necessary to ignore the "/" when performing a UrlEncode. For specific situations, please refer to the “Coding Specification”.

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

Coding specifications

• Resolvable contents: All request/response body contents are now encoded in UTF-8. Support for additional encoding types will be added in the future.

• Upon request, UrlEncode must be performed for the following items:

  • Object name: The character "/" is ignored for Resource UrlEncode.
  • Query string Value.
  • x-bce-copy-source: The character "/" is ignored.
  • Custom Meta: Meta values only support visible ASCII characters. For characters not supported, it is recommended to use UrlEncode processing.

Request syntax style

The BOS API request syntax supports formats without "/v {version}/" and is compatible with formats including "/v {version}/". For example, both of the following API call methods for GetObject are correct.

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

Specification for the number and size of resources

• The number of bucket available to users is 100. If you need more buckets, you can apply through the Ticket System.
• There is no restriction on the number of objects within a bucket.
• The maximum size for a single object is 5 TB.
• The size of a user request header must not exceed 8 KB. Within this limit, user-defined meta (x-bce-meta-) must not exceed 2 KB; the meta value cannot be null and must support only ASCII format.

Naming convention

Bucket format requirements:

• Only lowercase letters, numbers, and hyphens (“-”) are allowed.
• A bucket name must start and end with a lowercase letter or number.
• Bucket names must be 3 to 63 characters in length.

Object format requirements: UTF-8 characters with a maximum length of 1,024 bytes.

Date and time

Dates and times can be expressed in various ways. For consistency, all date and time fields specified in the HTTP standard adhere to GMT unless otherwise stated. Other date and time formats consistently follow UTC time based on ISO 8601, with the following constraints:

• Date shall be expressed in the format of YYYY-MM-DD. For example, 2014-06-01 represents June 1, 2014.
• Time shall be expressed in the hh:mm:ss + capital letter Z format, and capital letter Z indicates UTC time. For example, 23:00:10Z represents 23:00:10 UTC.
• When involving date and time, insert an uppercase letter T between them. For example, 2014-06-01T23:00:10Z represents 23:00:10 UTC on June 1, 2014.