forked from docs/doc-exports
Wang , Deng Ke
60010eb9d0
Reviewed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com> Co-authored-by: Wang , Deng Ke <wangdengke2@huawei.com> Co-committed-by: Wang , Deng Ke <wangdengke2@huawei.com>
172 lines
16 KiB
HTML
172 lines
16 KiB
HTML
<a name="dds_api_0016"></a><a name="dds_api_0016"></a>
|
|
|
|
<h1 class="topictitle1">REST APIs</h1>
|
|
<div id="body33821816"><p id="dds_api_0016__p7945016142655">API requests sent by third-party applications to public cloud services must be authenticated using signatures.</p>
|
|
<p id="dds_api_0016__p29368960143850">Public cloud APIs follow RESTful API design rules.</p>
|
|
<p id="dds_api_0016__a43d1d1a130ea44338355338cae1cdf56">In REST, specific information or data on a network is represented by resources. REST allows users to access service resources by creating, querying, updating, and deleting resources.</p>
|
|
<p id="dds_api_0016__p662413466426">A REST API request and response are divided into the following parts:</p>
|
|
<ul id="dds_api_0016__en-us_topic_0113746487_ul36846408206"><li id="dds_api_0016__en-us_topic_0113746487_li668494019204">Request URI</li><li id="dds_api_0016__en-us_topic_0113746487_li860984810208">Request header</li><li id="dds_api_0016__en-us_topic_0113746487_li897725422013">Request body</li><li id="dds_api_0016__en-us_topic_0113746487_li42171202213">Response header</li><li id="dds_api_0016__en-us_topic_0113746487_li10421866214">Response body</li></ul>
|
|
<div class="section" id="dds_api_0016__en-us_topic_0113746487_section697653216219"><h4 class="sectiontitle">Request URI</h4><p id="dds_api_0016__en-us_topic_0113746487_p1327834192114">A request URI consists of the following:</p>
|
|
<p id="dds_api_0016__en-us_topic_0113746487_p015994616212"><strong id="dds_api_0016__en-us_topic_0113746487_b11186155382110">{URI-scheme}://{Endpoint}/{resource-path}?{query-string}</strong></p>
|
|
<p id="dds_api_0016__en-us_topic_0113746487_p16960034182113">Although a request URI is included in a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.</p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="dds_api_0016__en-us_topic_0113746487_table4443194632512" frame="border" border="1" rules="all"><caption><b>Table 1 </b>URI parameter description</caption><thead align="left"><tr id="dds_api_0016__en-us_topic_0113746487_row1944414616258"><th align="left" class="cellrowborder" valign="top" width="26%" id="mcps1.3.6.5.2.3.1.1"><p id="dds_api_0016__en-us_topic_0113746487_p1644484692510"><strong id="dds_api_0016__b205415181362">Parameter</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="74%" id="mcps1.3.6.5.2.3.1.2"><p id="dds_api_0016__en-us_topic_0113746487_p174441146142511"><strong id="dds_api_0016__b130291913610">Description</strong></p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="dds_api_0016__en-us_topic_0113746487_row10444144620259"><td class="cellrowborder" valign="top" width="26%" headers="mcps1.3.6.5.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p154446465251">URI-scheme</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="74%" headers="mcps1.3.6.5.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p8444144692517">Specifies the protocol used for transmitting requests.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_row444414692513"><td class="cellrowborder" valign="top" width="26%" headers="mcps1.3.6.5.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p7444194610257">Endpoint</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="74%" headers="mcps1.3.6.5.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p244474613259">Specifies the domain name or IP address of the server bearing the REST service endpoint.</p>
|
|
<p id="dds_api_0016__p716619178377">To obtain the parameter value, see <a href="https://docs.otc.t-systems.com/en-us/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_row1744454612520"><td class="cellrowborder" valign="top" width="26%" headers="mcps1.3.6.5.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p14442468257">resource-path</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="74%" headers="mcps1.3.6.5.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p1844412467258">Specifies the API access path for performing a specified operation. Obtain this value from the URI of the API, for example, <strong id="dds_api_0016__b842352706134656">v3/auth/tokens</strong>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_row184441346152515"><td class="cellrowborder" valign="top" width="26%" headers="mcps1.3.6.5.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p4444154692516">query-string</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="74%" headers="mcps1.3.6.5.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p1444414622514">This parameter is optional. For example, you can set it to API version or resource selection criteria.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="dds_api_0016__en-us_topic_0113746487_section5296154118345"><h4 class="sectiontitle">Request Methods</h4><div class="p" id="dds_api_0016__p46347563325">HTTP methods, which are also called operations or actions, specify the type of operations that you are requesting.
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="dds_api_0016__en-us_topic_0113746487_table1961229113819" frame="border" border="1" rules="all"><caption><b>Table 2 </b>HTTP methods</caption><thead align="left"><tr id="dds_api_0016__en-us_topic_0113746487_row86141913816"><th align="left" class="cellrowborder" valign="top" width="30%" id="mcps1.3.7.2.1.2.3.1.1"><p id="dds_api_0016__en-us_topic_0113746487_p186147910387"><strong id="dds_api_0016__en-us_topic_0113746487_b1093312238395">Method</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="70%" id="mcps1.3.7.2.1.2.3.1.2"><p id="dds_api_0016__en-us_topic_0113746487_p166141293387"><strong id="dds_api_0016__b18836332155546">Description</strong></p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="dds_api_0016__en-us_topic_0113746487_row146141194381"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.7.2.1.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p12831539123914">GET</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.7.2.1.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p2831123916397">Requests a server to return the specified resources.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_row56141190384"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.7.2.1.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p68311239113912">POST</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.7.2.1.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p1583133918391">Requests a server to add resources or perform special operations.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_row861411903812"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.7.2.1.2.3.1.1 "><p id="dds_api_0016__en-us_topic_0113746487_p1183153943916">DELETE</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.7.2.1.2.3.1.2 "><p id="dds_api_0016__en-us_topic_0113746487_p6831163914392">Requests a server to delete specified resources, for example, an object.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="dds_api_0016__section479119143310"><h4 class="sectiontitle">Request Header</h4><p id="dds_api_0016__p56967114331">You can also add additional fields to the request header, for example, the fields required by a specified URI and an HTTP method. <a href="#dds_api_0016__table18389930">Table 3</a> lists common request header fields.</p>
|
|
|
|
<div class="tablenoborder"><a name="dds_api_0016__table18389930"></a><a name="table18389930"></a><table cellpadding="4" cellspacing="0" summary="" id="dds_api_0016__table18389930" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="dds_api_0016__row24749807"><th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.8.3.2.5.1.1"><p id="dds_api_0016__p58577354"><strong id="dds_api_0016__b84235270691445">Name</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.8.3.2.5.1.2"><p id="dds_api_0016__p47145209"><strong id="dds_api_0016__b84235270611143">Description</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.8.3.2.5.1.3"><p id="dds_api_0016__p60665573"><strong id="dds_api_0016__en-us_topic_0091754394_b842352706102346">Mandatory</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.8.3.2.5.1.4"><p id="dds_api_0016__p14964341"><strong id="dds_api_0016__b842352706103845">Example</strong></p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="dds_api_0016__row4152081"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.1 "><p id="dds_api_0016__p774306">Content-Type</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.2 "><p id="dds_api_0016__p62718864">Specifies the MIME type of the request body.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.3 "><p id="dds_api_0016__p47063234">Yes</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.4 "><p id="dds_api_0016__p54025633">application/json</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__row16468652"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.1 "><p id="dds_api_0016__p58892473">Content-Length</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.2 "><p id="dds_api_0016__p5560998">Specifies the length of the request body. The unit is byte.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.3 "><p id="dds_api_0016__p47787675">This parameter is optional for POST requests, but must be left blank for GET requests.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.4 "><p id="dds_api_0016__p45596481">3495</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__row102809013611"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.1 "><p id="dds_api_0016__p5563313">X-Project-Id</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.2 "><p id="dds_api_0016__p47975183">Specifies the project ID. For details about how to obtain the project ID, see <a href="dds_projectid.html">Obtaining a Project ID</a>.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.3 "><p id="dds_api_0016__p60784581">No</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.4 "><p id="dds_api_0016__p24604028">e9993fc787d94b6c886cbaa340f9c0f4</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__row7715150"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.1 "><p id="dds_api_0016__p20947391">X-Auth-Token</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.2 "><p id="dds_api_0016__p19017142">Specifies the user token.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.3 "><p id="dds_api_0016__p63993496">Yes</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.8.3.2.5.1.4 "><p id="dds_api_0016__p16090703">-</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="dds_api_0016__en-us_topic_0113746487_section1437471411"><h4 class="sectiontitle">(Optional) Request Body</h4><p id="dds_api_0016__en-us_topic_0113746487_p76011911717">A request body is generally sent in a structured format (for example, JSON or XML), corresponding to <strong id="dds_api_0016__b589791263516">Content-Type</strong> in the request header, and is used to transfer content other than the request header.</p>
|
|
<p id="dds_api_0016__en-us_topic_0113746487_p07341123474">If the request body contains full-width characters, convert the full-width characters into the UTF-8 encoding format.</p>
|
|
</div>
|
|
<div class="section" id="dds_api_0016__en-us_topic_0113746487_section61333484715"><h4 class="sectiontitle">Response Headers</h4><p id="dds_api_0016__en-us_topic_0113746487_p1368914492710">A response header consists of the following two parts:</p>
|
|
<ul id="dds_api_0016__en-us_topic_0113746487_ul7241441888"><li id="dds_api_0016__en-us_topic_0113746487_li72484989">An HTTP status code, which is a service-defined status code indicating a success or an error</li><li id="dds_api_0016__li12411149132412">Additional fields, for example <strong id="dds_api_0016__b842352706142714">Content-Type</strong><div class="p" id="dds_api_0016__p1747493716311"><a href="#dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139">Table 4</a> lists common response header fields.
|
|
<div class="tablenoborder"><a name="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139"></a><a name="en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139"></a><table cellpadding="4" cellspacing="0" summary="" id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_table3877208613139" frame="border" border="1" rules="all"><caption><b>Table 4 </b>Common response headers</caption><thead align="left"><tr id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_row3771309013139"><th align="left" class="cellrowborder" valign="top" width="19.15%" id="mcps1.3.10.3.2.2.2.2.4.1.1"><p id="dds_api_0016__p66697461"><strong id="dds_api_0016__b853217512492">Name</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="49.830000000000005%" id="mcps1.3.10.3.2.2.2.2.4.1.2"><p id="dds_api_0016__p33785274"><strong id="dds_api_0016__b1257416612495">Description</strong></p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="31.019999999999996%" id="mcps1.3.10.3.2.2.2.2.4.1.3"><p id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_p5162099210429"><strong id="dds_api_0016__b66630724911">Example</strong></p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_row1673548413139"><td class="cellrowborder" valign="top" width="19.15%" headers="mcps1.3.10.3.2.2.2.2.4.1.1 "><p id="dds_api_0016__p45638969">Date</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="49.830000000000005%" headers="mcps1.3.10.3.2.2.2.2.4.1.2 "><p id="dds_api_0016__p5769005">Standard HTTP header field, which represents the date and time at which the message was originated. The format is defined by RFC 822.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="31.019999999999996%" headers="mcps1.3.10.3.2.2.2.2.4.1.3 "><p id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_p59381193104213">Wed, 27 Dec 2018 06:49:46 GMT</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__row89631076206"><td class="cellrowborder" valign="top" width="19.15%" headers="mcps1.3.10.3.2.2.2.2.4.1.1 "><p id="dds_api_0016__p14341151362016">Content-Length</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="49.830000000000005%" headers="mcps1.3.10.3.2.2.2.2.4.1.2 "><p id="dds_api_0016__p93417134203">Standard HTTP header field, which specifies the size of the entity body, in decimal number of bytes, sent to the recipient.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="31.019999999999996%" headers="mcps1.3.10.3.2.2.2.2.4.1.3 "><p id="dds_api_0016__p63435135202">-</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_row2720466144725"><td class="cellrowborder" valign="top" width="19.15%" headers="mcps1.3.10.3.2.2.2.2.4.1.1 "><p id="dds_api_0016__p44855704">Content-Type</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="49.830000000000005%" headers="mcps1.3.10.3.2.2.2.2.4.1.2 "><p id="dds_api_0016__p445862101910">Standard HTTP header field, which specifies the media type of the entity body sent to the recipient.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="31.019999999999996%" headers="mcps1.3.10.3.2.2.2.2.4.1.3 "><p id="dds_api_0016__en-us_topic_0113746487_en-us_topic_0020536997_p21477025104246">application/json</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</li></ul>
|
|
</div>
|
|
<div class="section" id="dds_api_0016__en-us_topic_0113746487_section2045571671419"><h4 class="sectiontitle">(Optional) Response Body</h4><p id="dds_api_0016__en-us_topic_0113746487_p64711881416">A response body is generally returned in a structured format (for example, JSON or XML), corresponding to <strong id="dds_api_0016__b911849175515">Content-Type</strong> in the response header, and is used to transfer content other than the response header.</p>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="dds_api_0014.html">API Calling</a></div>
|
|
</div>
|
|
</div>
|
|
|