Initiate RESTful API requests - Object Storage Service - Alibaba Cloud Documentation Center

Domain name format

All requests to OSS over OSS domain names, except the GetService (ListBuckets)and DescribeRegions requests, contain bucket information in the domain names.

A bucket domain name uses the BucketName.Endpoint format. BucketName is the bucket name, and Endpoint is the regional endpoint.

OSS endpoints include internal endpoints, public endpoints, and acceleration endpoints.

Note

Each region has a distinct endpoint. For more information, see Regions and Endpoints.
Internal and public endpoints require no additional configuration.
To use an acceleration endpoint, enable transfer acceleration first. For more information, see Access OSS using transfer acceleration.
You can use a custom domain name instead of a public endpoint. For more information, see Access OSS through a custom domain nameor Access OSS through a custom domain name.

For example, the following endpoints apply to the China (Hangzhou) region:

Request style

For security reasons, OSS accepts only virtual hosted-style URLs, not path-style URLs. A virtual hosted-style URL includes the bucket name.

Virtual hosted-style URL format:

https://BucketName.Endpoint/objectName

Example:

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/demo.png

Request header format

A RESTful API request to OSS uses the following header format:

GET / HTTP/1.1
Host: BucketName.Endpoint
Date: GMT Date
Authorization: SignatureValue

Header	Type	Description
Date	String	GMT time per HTTP/1.1. Example: Sun, 05 Sep 2021 23:00:00 GMT. This header is empty by default.
Host	String	Access domain name in `BucketName.Endpoint` format. This header is empty by default.
Authorization	String	Authentication information that verifies the request. This header is empty by default. Scenario: non-anonymous requests.

Sample requests

Sample request for a virtual hosted-style URL

Sample OSS resources:

Bucket name: examplebucket
Region: oss-cn-hangzhou
Object name: demo.png

Sample URL:

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/demo.png

Sample requests:

GET /demo.png HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Sample request for a custom domain name

Sample custom domain name:

www.example.com

Sample OSS resources:

Bucket name: examplebucket
Object name: demo.png

Sample URL:

https://www.example.com/demo.png

Sample requests:

GET /demo.png HTTP/1.1
Host: example.com
Date: GMT Date
Authorization: SignatureValue

Signature methods

Two methods are available to sign RESTful API requests:

Add signatures to request headers: Recommended for most cases. Include signatures in the Authorization header.
Add signatures to URLs: Signed URLs grant temporary access to anyone with the URL, which poses security risks. Use this method to provide time-limited authorized access to third parties. Add signatures to URLs.

The following table compares the two methods.

Item	Add signatures to request headers	Add signatures to URLs
Configuration of the Expires parameter	No	Yes
Common request methods	GET, POST, PUT, and DELETE	GET and PUT
Time format	The Date header specifies the request time in GMT format. Important If the Date header differs from the server time by more than 15 minutes, OSS rejects the request with HTTP status code 403.	The Expires parameter specifies the URL expiration time as a Unix timestamp. Important If OSS receives the request after the Expires value, a timeout error is returned.
URL-encoded signatures	No	Yes

API operations

For more information about the API operations that are provided by OSS, see API overview.

Object Storage Service:Initiate RESTful API requests