Constructing a Request

This section describes the structure of a REST API request.

Request URI

SFS uses URI to locate specific general-purpose file systems 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://[filesystem.]domain[:port]/[?param]

**Table 1** URI parameters
Parameter	Description	Mandatory
protocol	Protocol used for sending requests, which can be either HTTP or HTTPS. HTTPS is a protocol that ensures secure access to resources. SFS supports both HTTP and HTTPS.	Yes
filesystem	Resource path of a general-purpose file system, identifying only one general-purpose file system in SFS	No
domain	Domain name or IP address of the server for storing resources	Yes
port	Port enabled for protocols used for sending requests. The value varies with software server deployment. If no port number is specified, the protocol uses the default port. Each transmission protocol has a default port. For example, HTTP uses port 80 and HTTPS uses port 443. In SFS, the default HTTP port is 80 and default HTTPS port is 443.	No
param	A specific resource contained by a general-purpose file system. Default value of this parameter indicates that the file system itself is obtained.	No

All API requests except those for listing file systems must contain the general-purpose file system name. To ensure DNS resolution performance and reliability, SFS requires that the general-purpose file system name must precede the domain when a request carrying a file system name is constructed to form a three-level domain name, also mentioned as virtual-hosted-style access domain name.

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 SFS
Method	Description
GET	Requests the server to return specific resources, for example, to list general-purpose file systems.
PUT	Requests the server to update specific resources, for example, to create general-purpose file systems.
POST	Requests a server to add resources or perform special operations.
DELETE	Requests the server to delete specified resources, for example, general-purpose file systems.
HEAD	Same as GET except that the server must return only the response header.
OPTIONS	Requests the server to check whether the user has the permissions to operate a resource.

Request Headers

Refers to optional and additional request fields, for example a field required by a specific URI or HTTP method. Table 3 describes some common request header fields.

**Table 3** Common request headers
Header	Description	Mandatory
Authorization	Signature information contained in a request message Type: string No default value.	Yes
Content-Length	The message length (excluding headers) defined in RFC 2616 Type: string No default value. Condition: required for PUT requests and those requests that load XML content.	Conditionally required
Content-Type	The content type of the requested resource, for example, text/plain Type: string No default value.	No
Date	The time when a request is initiated, for example, Wed, 27 Jun 2018 13:39:15 +0000. Type: string No default value. Condition: optional for requests containing header x-obs-date, required for other requests.	Conditionally required
Host	The host address, for example, filesystem.sfs3.region.myhuaweicloud.com. Type: string No default value.	Yes

(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 Chinese characters, these characters must be encoded in 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 SFS 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 coding.

Parent topic: Calling APIs

Previous topic: Calling APIs

Next topic: Authentication

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot