forked from docs/doc-exports
lizaoxu
b47ac2cabb
Reviewed-by: Muller, Martin <martin.muller@t-systems.com> Co-authored-by: lizaoxu <lizaoxu@huawei.com> Co-committed-by: lizaoxu <lizaoxu@huawei.com>
178 lines
19 KiB
HTML
178 lines
19 KiB
HTML
<a name="sfs_02_0101"></a><a name="sfs_02_0101"></a>
|
|
|
|
<h1 class="topictitle1">Constructing a Request</h1>
|
|
<div id="body0000001338755298"><p id="sfs_02_0101__en-us_topic_0000001263228726_a43d1d1a130ea44338355338cae1cdf56">This section describes the structure of a REST API request.</p>
|
|
<div class="section" id="sfs_02_0101__en-us_topic_0000001263228726_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="sfs_02_0101__en-us_topic_0000001263228726_p61456874">SFS uses URI to locate specific file systems and their parameters. Use URIs when you want to operate resources.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p16240961">The following provides a common URI format. The parameters in square brackets [ ] are optional.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p12437161441413"><strong id="sfs_02_0101__en-us_topic_0000001263228726_b111541655132712">protocol://<strong id="sfs_02_0101__en-us_topic_0000001263228726_b6154155592713">[filesystem</strong>.<strong id="sfs_02_0101__en-us_topic_0000001263228726_b1915495512279">]</strong>domain[:port]/[?param]</strong></p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="sfs_02_0101__en-us_topic_0000001263228726_table40449485" frame="border" border="1" rules="all"><caption><b>Table 1 </b>URI parameters</caption><thead align="left"><tr id="sfs_02_0101__en-us_topic_0000001263228726_row6511324"><th align="left" class="cellrowborder" valign="top" width="13.13%" id="mcps1.3.2.5.2.4.1.1"><p id="sfs_02_0101__en-us_topic_0000001263228726_p57655222">Parameter</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="73.74000000000001%" id="mcps1.3.2.5.2.4.1.2"><p id="sfs_02_0101__en-us_topic_0000001263228726_p39561425">Description</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="13.13%" id="mcps1.3.2.5.2.4.1.3"><p id="sfs_02_0101__en-us_topic_0000001263228726_p50358869">Mandatory</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="sfs_02_0101__en-us_topic_0000001263228726_row52536552"><td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p27602357">protocol</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="73.74000000000001%" headers="mcps1.3.2.5.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p21198434">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.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p39351575">Yes</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row88287534152"><td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p1930030181620">filesystem</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="73.74000000000001%" headers="mcps1.3.2.5.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p930030121615">Resource path of a file system, identifying only one file system in SFS</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p3300803163">No</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row55346801513"><td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p135344812156">domain</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="73.74000000000001%" headers="mcps1.3.2.5.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p323103261516">Domain name or IP address of the server for saving resources</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p125929367153">Yes</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row53201908"><td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p14387307">port</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="73.74000000000001%" headers="mcps1.3.2.5.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p24521247">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 value. Each transmission protocol has its default port number. For example, HTTP uses port number <strong id="sfs_02_0101__en-us_topic_0000001263228726_b1444577227162034">80</strong> and HTTPS uses port number <strong id="sfs_02_0101__en-us_topic_0000001263228726_b41545509162034">443</strong> by default.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p25031604">In SFS, HTTP port number is <strong id="sfs_02_0101__en-us_topic_0000001263228726_b16741611132511">80</strong> and that of HTTPS is <strong id="sfs_02_0101__en-us_topic_0000001263228726_b12904131772518">443</strong>.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p14294078">No</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row13437443"><td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p14691104">param</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="73.74000000000001%" headers="mcps1.3.2.5.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p49128794">A specific resource contained by a file system. Default value of this parameter indicates that the file system itself is obtained.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="13.13%" headers="mcps1.3.2.5.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p45866588">No</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="notice" id="sfs_02_0101__en-us_topic_0000001263228726_note449230598"><span class="noticetitle"><img src="public_sys-resources/notice_3.0-en-us.png"> </span><div class="noticebody"><p id="sfs_02_0101__en-us_topic_0000001263228726_p169401149185116">All API requests except those for the file system list must contain the file system name. Based on the DNS resolution performance and reliability, SFS requires that the file system name must be placed in front of the <strong id="sfs_02_0101__en-us_topic_0000001263228726_b321515165217">domain</strong> when a request carrying a file system name is constructed to form a third-level domain name, also mentioned as virtual hosting access domain name.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="sfs_02_0101__en-us_topic_0000001263228726_section580035055419"><h4 class="sectiontitle">Request Method</h4><p id="sfs_02_0101__en-us_topic_0000001263228726_p65661618145510">HTTP methods, which are also called operations or actions, specify the type of operations that you are requesting.</p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="sfs_02_0101__en-us_topic_0000001263228726_table1123134922518" frame="border" border="1" rules="all"><caption><b>Table 2 </b>REST request methods supported by General Purpose File System</caption><thead align="left"><tr id="sfs_02_0101__en-us_topic_0000001263228726_row65706590"><th align="left" class="cellrowborder" valign="top" width="15.15%" id="mcps1.3.3.3.2.3.1.1"><p id="sfs_02_0101__en-us_topic_0000001263228726_p20633546">Method</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="84.85000000000001%" id="mcps1.3.3.3.2.3.1.2"><p id="sfs_02_0101__en-us_topic_0000001263228726_p60704555">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="sfs_02_0101__en-us_topic_0000001263228726_row18121961"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p58592747">GET</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p48392090">Requests the server to return specific resources, for example, to list file systems.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row32875629"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p45680330">PUT</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p9119239">Requests the server to update specific resources, for example, creating file systems.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row14964289"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p4147890">POST</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p434775">Requests a server to add resources or perform special operations.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row35216792"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p33987935">DELETE</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p1559313">Requests the server to delete specified resources, for example, file systems.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row14033823"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p62997855">HEAD</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p2552640">Same as GET except that the server must return only the response header.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row22973764"><td class="cellrowborder" valign="top" width="15.15%" headers="mcps1.3.3.3.2.3.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p48935609">OPTIONS</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="84.85000000000001%" headers="mcps1.3.3.3.2.3.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p4361378">Requests the server to check whether the user has the permissions to operate a resource.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="sfs_02_0101__en-us_topic_0000001263228726_section1454211155819"><h4 class="sectiontitle">Request Headers</h4><p id="sfs_02_0101__en-us_topic_0000001263228726_p155521124165511">Refers to optional and additional request fields, for example a field required by a specific URI or HTTP method. <a href="#sfs_02_0101__en-us_topic_0000001263228726_table25197309">Table 3</a> describes some common request header fields.</p>
|
|
|
|
<div class="tablenoborder"><a name="sfs_02_0101__en-us_topic_0000001263228726_table25197309"></a><a name="en-us_topic_0000001263228726_table25197309"></a><table cellpadding="4" cellspacing="0" summary="" id="sfs_02_0101__en-us_topic_0000001263228726_table25197309" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="sfs_02_0101__en-us_topic_0000001263228726_row56260471"><th align="left" class="cellrowborder" valign="top" width="20.380000000000003%" id="mcps1.3.4.3.2.4.1.1"><p id="sfs_02_0101__en-us_topic_0000001263228726_p60804269">Header</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="58.87%" id="mcps1.3.4.3.2.4.1.2"><p id="sfs_02_0101__en-us_topic_0000001263228726_p26198756">Description</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="20.75%" id="mcps1.3.4.3.2.4.1.3"><p id="sfs_02_0101__en-us_topic_0000001263228726_p41724483">Mandatory</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="sfs_02_0101__en-us_topic_0000001263228726_row24239987"><td class="cellrowborder" valign="top" width="20.380000000000003%" headers="mcps1.3.4.3.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p17281948">Authorization</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="58.87%" headers="mcps1.3.4.3.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p57660517">Signature information contained in a request message</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p49182605">Type: string</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p39990262">No default value.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p24368041">Conditional: optional for anonymous requests and required for other requests.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.75%" headers="mcps1.3.4.3.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p27654330">Conditionally required</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row47562386"><td class="cellrowborder" valign="top" width="20.380000000000003%" headers="mcps1.3.4.3.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p27348077">Content-Length</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="58.87%" headers="mcps1.3.4.3.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p601777">The message length (excluding headers) defined in RFC 2616</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p5415993">Type: string</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p48743940">No default value.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p36042284">Conditional: required for PUT requests and those requests that load XML content.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.75%" headers="mcps1.3.4.3.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p33743900">Conditionally required</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row35259646"><td class="cellrowborder" valign="top" width="20.380000000000003%" headers="mcps1.3.4.3.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p37459059">Content-Type</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="58.87%" headers="mcps1.3.4.3.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p14284953">The content type of the requested resource, for example, <strong id="sfs_02_0101__en-us_topic_0000001263228726_b17772351">text</strong>/<strong id="sfs_02_0101__en-us_topic_0000001263228726_b25733436">plain</strong></p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p61455718">Type: string</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p16230551">No default value.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.75%" headers="mcps1.3.4.3.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p39606294">No</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row20912334"><td class="cellrowborder" valign="top" width="20.380000000000003%" headers="mcps1.3.4.3.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p16177456">Date</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="58.87%" headers="mcps1.3.4.3.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p35305575">The time when a request is initiated, for example, <strong id="sfs_02_0101__en-us_topic_0000001263228726_b12662139205219">Wed, 27 Jun 2018 13:39:15 +0000</strong>.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p49314726">Type: string</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p41179355">No default value.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p35069879">Conditional: optional for anonymous requests or those requests containing header <strong id="sfs_02_0101__en-us_topic_0000001263228726_b109335711495028">x-obs-date</strong>, required for other requests.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.75%" headers="mcps1.3.4.3.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p22087952">Conditionally required</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="sfs_02_0101__en-us_topic_0000001263228726_row64573848"><td class="cellrowborder" valign="top" width="20.380000000000003%" headers="mcps1.3.4.3.2.4.1.1 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p63099185">Host</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="58.87%" headers="mcps1.3.4.3.2.4.1.2 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p97201251192612">The host address, for example, <strong id="sfs_02_0101__b593863861818">filesystem.sfs3.region.example.com</strong>.</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p29734368">Type: string</p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p66282721">No default value.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.75%" headers="mcps1.3.4.3.2.4.1.3 "><p id="sfs_02_0101__en-us_topic_0000001263228726_p191303">Yes</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="sfs_02_0101__en-us_topic_0000001263228726_section14612192315587"><h4 class="sectiontitle">(Optional) Request Body</h4><p id="sfs_02_0101__en-us_topic_0000001263228726_p23132011213">A request body is generally sent in a structured format (for example, JSON or XML). It corresponds to <strong id="sfs_02_0101__en-us_topic_0000001263228726_b367972613329">Content-Type</strong> in the request header and is used to transfer content other than the request header. </p>
|
|
<p id="sfs_02_0101__en-us_topic_0000001263228726_p43235913117">The request body varies according to the APIs. Certain APIs do not require the request body, such as the GET and DELETE APIs.</p>
|
|
</div>
|
|
<div class="section" id="sfs_02_0101__en-us_topic_0000001263228726_section140743661613"><h4 class="sectiontitle">Sending a Request</h4><p id="sfs_02_0101__en-us_topic_0000001263228726_abe87411d02f441d8acf5a5f63d52edbe">There are two methods to initiate requests based on the constructed request messages:</p>
|
|
<ul id="sfs_02_0101__en-us_topic_0000001263228726_u69bb0fd8d11a4e428f4e6fedc1515950"><li id="sfs_02_0101__en-us_topic_0000001263228726_la8e5f209e37b4c9eb0ae66f73d0ec1f0">cURL<p id="sfs_02_0101__en-us_topic_0000001263228726_a04f9f8ebd6674f36b25f63e65a92dcf2"><a name="sfs_02_0101__en-us_topic_0000001263228726_la8e5f209e37b4c9eb0ae66f73d0ec1f0"></a><a name="en-us_topic_0000001263228726_la8e5f209e37b4c9eb0ae66f73d0ec1f0"></a>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 <a href="https://curl.haxx.se/" target="_blank" rel="noopener noreferrer">https://curl.haxx.se/</a>. cURL cannot calculate signatures. When cURL is used, only anonymous public SFS resources can be accessed.</p>
|
|
</li><li id="sfs_02_0101__en-us_topic_0000001263228726_lae3f7b6d508b43cd8565d0e8c4d9700b">Coding<p id="sfs_02_0101__en-us_topic_0000001263228726_a02b0199016c4467693bc9cd4dcd9d74f"><a name="sfs_02_0101__en-us_topic_0000001263228726_lae3f7b6d508b43cd8565d0e8c4d9700b"></a><a name="en-us_topic_0000001263228726_lae3f7b6d508b43cd8565d0e8c4d9700b"></a>You can use code to make API calls, and to assemble, send, and process request messages. It can be implemented by coding.</p>
|
|
</li></ul>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="sfs_02_0100.html">Calling APIs (General Purpose File System)</a></div>
|
|
</div>
|
|
</div>
|
|
|