Help Center/ Object Storage Service/ API Reference/ Calling APIs/ Constructing a Request
Updated on 2025-08-22 GMT+08:00
View PDF
Share

Constructing a Request

This section describes the structure of a REST API request.

Request URI

OBS uses URI to locate specific buckets, objects, and their parameters. Use URIs when you want to operate resources.

The following provides a common URI format. The parameters in square brackets [ ] are optional.

protocol://[bucket.]domain[:port][/object][?param]

Table 1 URI parameters

Parameter

Type

Mandatory

Description

protocol

String

Yes

Definition:

Protocol used for sending requests

Constraints:

None

Range:

  • HTTP: HyperText Transfer Protocol. Data is transmitted in plaintext. It is easy to be eavesdropped and tampered with. It is usually used to transmit website content that does not contain sensitive information, such as news.
  • HTTPS: HyperText Transfer Protocol Secure. Data is encrypted using SSL/TLS to provide secure and reliable communication. It is used to transmit sensitive information.

Default value:

None

bucket

String

No

Definition:

Bucket name

Constraints:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Default value:

None

domain

String

Yes

Definition:

Endpoint of each region

Constraints:

None

Range:

For details about region endpoints, see Regions and EndpointsRegions and Endpoints.

Default value:

None

port

String

No

Definition:

Port enabled for sending requests. The value varies with software server deployment.

Constraints:

None

Range:

In OBS, the default HTTP port is 80 and that of HTTPS is 443.

Default value:

If no port number is specified, the protocol uses the default value. Each transmission protocol has its default port number.

object

String

No

Definition:

Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name.

For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt.

Range:

The value is a string of 1 to 1024 characters.

Default value:

None

param

String

No

Definition:

Requested bucket and object

Constraints:

None

Range:

None

Default value:

If this parameter is not set, the bucket or object involved in the request is used by default.

All API requests except those for the bucket list must contain the bucket name. Based on the DNS resolution performance and reliability, OBS requires that the bucket name must be placed in front of the domain when a request carrying a bucket name is constructed to form a third-level domain name, also mentioned as virtual hosting access domain name.

For example, you have a bucket named test-bucket in the ap-southeast-1 region, and you want to access the ACL of an object named test-object in the bucket. The correct URL is https://test-bucket.obs.ap-southeast-1.myhuaweicloud.com/test-object?acl.

Request Method

HTTP methods, which are also called operations or actions, specify the type of operations that you are requesting.

Table 2 HTTP request methods supported by the OBS

Method

Description

GET

Requests that the server return a specific resource, for example, a bucket list or object.

PUT

Requests that the server update a specific resource, for example, creating a bucket or uploading an object.

POST

Requests that the server add a resource or perform a special operation, for example, initiating multipart uploads or assembling parts.

DELETE

Requests that the server delete specified resources, for example, an object.

HEAD

Requests that the server return the description of a specific resource, for example, object metadata.

OPTIONS

Requests that the server check whether the user has the operation permission for a resource. The CORS needs to be configured for the bucket.

Request Headers

Refers to optional and additional request fields, for example a field required by a specific URI or HTTP method. For details about the fields of common request headers, see Table 3.

Table 3 Common request headers

Header

Type

Mandatory (Yes/No)

Description

Authorization

String

Conditionally Yes

Definition:

Signature information contained in a request message

Constraints:

This header is optional for anonymous requests and is mandatory for other requests.

Range:

None

Default value:

None

Content-Length

String

Conditionally Yes

Definition:

Length of a message (excluding the message header).

Constraints:

It is optional for the PUT operation and mandatory for the operation of loading XML files.

Range:

None

Default value:

None

Content-Type

String

No

Definition:

The content type of the requested resource, for example, text/plain

Constraints:

None

Range:

For details about the common content types, see Common Content Types.

Default value:

If this header is not carried when an object is uploaded, the value of Content-Type returned by default when the object is downloaded is binary/octet-stream.

Date

String

Conditionally Yes

Definition:

Time when a request is initiated, for example, Wed, 27 Jun 2018 13:39:15 +0000

Constraints:

This header is optional for anonymous requests or requests whose headers contain the x-obs-date field and mandatory for other requests.

Range:

None

Default value:

None

Host

String

Yes

Definition:

Access domain name of a bucket. The format is BucketName.Endpoint.

Example: examplebucketname.obs.region.myhuaweicloud.com

Constraints:

The constraints on bucket names are as follows:

  • A bucket name must be unique across all accounts and regions.
  • A bucket name:
    • Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed.
    • Cannot be formatted as an IP address.
    • Cannot start or end with a hyphen (-) or period (.).
    • Cannot contain two consecutive periods (..), for example, my..bucket.
    • Cannot contain a period (.) and a hyphen (-) adjacent to each other, for example, my-.bucket or my.-bucket.
  • If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket attributes comply with those set in the first creation request.

Range:

For details about region endpoints, see Regions and EndpointsRegions and Endpoints.

Default value:

None

(Optional) Request Body

A request body is generally sent in a structured format (for example, JSON or XML). It corresponds to Content-Type in the request header and is used to transfer content other than the request header. If the request body contains full-width characters, these characters must be coded using UTF-8.

The request body varies according to the APIs. Certain APIs do not require the request body, such as the GET and DELETE APIs.

Sending a Request

There are two methods to initiate requests based on the constructed request messages:

  • cURL

    cURL is a command-line tool used to perform URL operations and transmit information. cURL acts as an HTTP client that can send HTTP requests to the server and receive response messages. cURL is applicable to API debugging. For more information about cURL, visit https://curl.haxx.se/. cURL cannot calculate signatures. When cURL is used, only anonymous public OBS resources can be accessed.

  • Coding

    You can use code to make API calls, and to assemble, send, and process request messages. It can be implemented by using the SDK or coding.

Parent topic: Calling APIs