forked from docs/doc-exports
liusiying77
fdbbe7547a
Reviewed-by: Bobkova, Natalia <natalia.bobkova@t-systems.com> Reviewed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com> Co-authored-by: liusiying77 <liusiying@huawei.com> Co-committed-by: liusiying77 <liusiying@huawei.com>
145 lines
20 KiB
HTML
145 lines
20 KiB
HTML
<a name="lts_api_0004"></a><a name="lts_api_0004"></a>
|
|
|
|
<h1 class="topictitle1">Making an API Request</h1>
|
|
<div id="body8662426"><p id="lts_api_0004__en-us_topic_0192137669_p15648656678">This section describes the structure of a REST API request, and uses the IAM API for <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">obtaining a user token</a> as an example to demonstrate how to call an API. The obtained token can then be used to authenticate the calling of other APIs.</p>
|
|
<div class="section" id="lts_api_0004__en-us_topic_0192137669_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="lts_api_0004__en-us_topic_0192137669_p729531715312">A request URI is in the following format:</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p11610193811547"><strong id="lts_api_0004__en-us_topic_0192137669_b3129104565416">{URI-scheme} :// {<strong id="lts_api_0004__en-us_topic_0192137669_b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p19153141415558">Although a request URI is included in the request header, most programming languages or frameworks require the request URI to be transmitted separately.</p>
|
|
<ul id="lts_api_0004__en-us_topic_0192137669_ul1252522141910"><li id="lts_api_0004__en-us_topic_0192137669_li189491651174717"><strong id="lts_api_0004__en-us_topic_0192137669_b20556134616513">URI-scheme</strong>:<p id="lts_api_0004__en-us_topic_0192137669_p1697825294716">Protocol used to transmit requests. All APIs use <strong id="lts_api_0004__en-us_topic_0192137669_b6529556195114">HTTPS</strong>.</p>
|
|
</li><li id="lts_api_0004__en-us_topic_0192137669_li9112205519475"><strong id="lts_api_0004__en-us_topic_0192137669_b1345291115213">Endpoint</strong>:<p id="lts_api_0004__en-us_topic_0192137669_p102531159154713">Domain name or IP address of the server bearing the REST service. The endpoint varies between services in different regions. It can be obtained from <a href="https://docs.otc.t-systems.com/en-us/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
|
|
</li><li id="lts_api_0004__en-us_topic_0192137669_li370732114810"><strong id="lts_api_0004__en-us_topic_0192137669_b0656221155615">resource-path</strong>:<p id="lts_api_0004__en-us_topic_0192137669_p8506183194819">Access path of an API for performing a specified operation. Obtain the path from the URI of an API. For example, the <strong id="lts_api_0004__en-us_topic_0192137669_b1883532203917">resource-path</strong> of the API used to obtain a user token is <span class="parmvalue" id="lts_api_0004__en-us_topic_0192137669_parmvalue12171235135215"><b>/v3/auth/tokens</b></span>.</p>
|
|
</li><li id="lts_api_0004__en-us_topic_0192137669_li773319494816"><strong id="lts_api_0004__en-us_topic_0192137669_b1483133815531">query-string</strong>:<p id="lts_api_0004__en-us_topic_0192137669_p1727319564810">Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "<em id="lts_api_0004__en-us_topic_0192137669_i206440394409">Parameter name</em>=<em id="lts_api_0004__en-us_topic_0192137669_i1728154534011">Parameter value</em>". For example, <span class="parmname" id="lts_api_0004__en-us_topic_0192137669_parmname78831849185619"><b>?limit=10</b></span> indicates that a maximum of 10 data records will be displayed.</p>
|
|
</li></ul>
|
|
<div class="note" id="lts_api_0004__en-us_topic_0192137669_note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="lts_api_0004__en-us_topic_0192137669_p163316534416">To simplify the URI display, each API is provided only with a <strong id="lts_api_0004__en-us_topic_0192137669_b23147725418">resource-path</strong> and a request method. The <strong id="lts_api_0004__en-us_topic_0192137669_b075991514468">URI-scheme</strong> of all APIs is <strong id="lts_api_0004__en-us_topic_0192137669_b88286217466">HTTPS</strong>, and the endpoints of all APIs in the same region are identical.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="lts_api_0004__en-us_topic_0192137669_section580035055419"><h4 class="sectiontitle">Request Methods</h4><p id="lts_api_0004__en-us_topic_0192137669_p65661618145510">The HTTPS protocol defines the following request methods that can be used to send a request to the server:</p>
|
|
<ul id="lts_api_0004__en-us_topic_0192137669_ul11356238151312"><li id="lts_api_0004__en-us_topic_0192137669_li1835819385137"><strong id="lts_api_0004__en-us_topic_0192137669_b2813413161415">GET</strong>: requests a server to return specified resources.</li><li id="lts_api_0004__en-us_topic_0192137669_li95631239131310"><strong id="lts_api_0004__en-us_topic_0192137669_b197251516111416">PUT</strong>: requests a server to update specified resources.</li><li id="lts_api_0004__en-us_topic_0192137669_li1554910413138"><strong id="lts_api_0004__en-us_topic_0192137669_b15973118121419">POST</strong>: requests a server to add resources or perform special operations.</li><li id="lts_api_0004__en-us_topic_0192137669_li8237114421314"><strong id="lts_api_0004__en-us_topic_0192137669_b19881220161420">DELETE</strong>: requests a server to delete specified resources, for example, objects.</li><li id="lts_api_0004__en-us_topic_0192137669_li165331349151317"><strong id="lts_api_0004__en-us_topic_0192137669_b1879172316148">HEAD</strong>: same as GET except that the server must return only the response header.</li><li id="lts_api_0004__en-us_topic_0192137669_li4440175411313"><strong id="lts_api_0004__en-us_topic_0192137669_b1512311262140">PATCH</strong>: requests a server to update a part of a specified resource. If the resource does not exist, a new resource will be created.</li></ul>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p3759142614815">For example, in the case of the API used to obtain a user token, the request method is <span class="parmname" id="lts_api_0004__en-us_topic_0192137669_parmname14980312195614"><b>POST</b></span>. The request is as follows:</p>
|
|
</div>
|
|
<div class="section" id="lts_api_0004__en-us_topic_0192137669_section1454211155819"><h4 class="sectiontitle">Request Header</h4><p id="lts_api_0004__en-us_topic_0192137669_p269363935616">You can also add additional header fields to a request, such as the fields required by a specified URI or HTTP method. For example, to request for the authentication information, add <span class="parmname" id="lts_api_0004__en-us_topic_0192137669_parmname14711723175013"><b>Content-Type</b></span>, which specifies the request body type.</p>
|
|
<div class="p" id="lts_api_0004__en-us_topic_0192137669_p56967114331">Common request header fields are as follows:
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="lts_api_0004__en-us_topic_0192137669_table1986821153312" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Common request header fields</caption><thead align="left"><tr id="lts_api_0004__en-us_topic_0192137669_row1286841153311"><th align="left" class="cellrowborder" valign="top" width="19.74%" id="mcps1.3.4.3.1.2.5.1.1"><p id="lts_api_0004__en-us_topic_0192137669_p178680183310">Parameter</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="26.479999999999997%" id="mcps1.3.4.3.1.2.5.1.2"><p id="lts_api_0004__en-us_topic_0192137669_p78688118335">Description</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="20.13%" id="mcps1.3.4.3.1.2.5.1.3"><p id="lts_api_0004__en-us_topic_0192137669_p58686123316">Mandatory</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="33.650000000000006%" id="mcps1.3.4.3.1.2.5.1.4"><p id="lts_api_0004__en-us_topic_0192137669_p48681314333">Example Value</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="lts_api_0004__en-us_topic_0192137669_row1286861153311"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.1.2.5.1.1 "><p id="lts_api_0004__en-us_topic_0192137669_p2086813163316">Host</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="26.479999999999997%" headers="mcps1.3.4.3.1.2.5.1.2 "><p id="lts_api_0004__en-us_topic_0192137669_p58681814333">Server domain name and port number of the resources being requested. The value can be obtained from the URL of the service API. The value is in the format of <em id="lts_api_0004__en-us_topic_0192137669_i14244154995310">Hostname</em>:<em id="lts_api_0004__en-us_topic_0192137669_i1558357205320">Port number</em>. If the port number is not specified, the default port is used. The default port number for <strong id="lts_api_0004__en-us_topic_0192137669_b473716914552">https</strong> is <strong id="lts_api_0004__en-us_topic_0192137669_b7330811155510">443</strong>.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.13%" headers="mcps1.3.4.3.1.2.5.1.3 "><p id="lts_api_0004__en-us_topic_0192137669_p886815123319">No</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p386811116333">This field is mandatory for AK/SK authentication.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.1.2.5.1.4 "><p id="lts_api_0004__en-us_topic_0192137669_p486814118330">code.test.com</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p5868161163317">or</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p786841123315">code.test.com:443</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="lts_api_0004__en-us_topic_0192137669_row386818143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.1.2.5.1.1 "><p id="lts_api_0004__en-us_topic_0192137669_p118689123320">Content-Type</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="26.479999999999997%" headers="mcps1.3.4.3.1.2.5.1.2 "><p id="lts_api_0004__en-us_topic_0192137669_p1486815116337">Type (or format) of the message body. The default value <strong id="lts_api_0004__en-us_topic_0192137669_b965464555617">application/json</strong> is recommended. Other values of this field will be provided for specific APIs if any.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.13%" headers="mcps1.3.4.3.1.2.5.1.3 "><p id="lts_api_0004__en-us_topic_0192137669_p1086812114335">Yes</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.1.2.5.1.4 "><p id="lts_api_0004__en-us_topic_0192137669_p1186841163310">application/json</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="lts_api_0004__en-us_topic_0192137669_row11868419337"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.1.2.5.1.1 "><p id="lts_api_0004__en-us_topic_0192137669_p178687119330">Content-Length</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="26.479999999999997%" headers="mcps1.3.4.3.1.2.5.1.2 "><p id="lts_api_0004__en-us_topic_0192137669_p178681813332">Length of the request body. The unit is byte.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.13%" headers="mcps1.3.4.3.1.2.5.1.3 "><p id="lts_api_0004__en-us_topic_0192137669_p18687183316">No</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.1.2.5.1.4 "><p id="lts_api_0004__en-us_topic_0192137669_p148689110334">3495</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="lts_api_0004__en-us_topic_0192137669_row2868171143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.1.2.5.1.1 "><p id="lts_api_0004__en-us_topic_0192137669_p586815118338">X-Project-Id</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="26.479999999999997%" headers="mcps1.3.4.3.1.2.5.1.2 "><p id="lts_api_0004__en-us_topic_0192137669_p1586811163312">Project ID. Obtain the project ID by following the instructions in <a href="lts_api_0006.html">Obtaining the Account ID, Project ID, Log Group ID, and Log Stream ID</a>.</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="20.13%" headers="mcps1.3.4.3.1.2.5.1.3 "><p id="lts_api_0004__en-us_topic_0192137669_p886812110335">No</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.1.2.5.1.4 "><p id="lts_api_0004__en-us_topic_0192137669_p198684143315">e9993fc787d94b6c886cbaa340f9c0f4</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
<div class="note" id="lts_api_0004__en-us_topic_0192137669_note13771123325011"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="lts_api_0004__en-us_topic_0192137669_p1513412221808">In addition to supporting token-based authentication, APIs also support authentication using access key ID/secret access key (AK/SK). During AK/SK-based authentication, an SDK is used to sign a request, and the <strong id="lts_api_0004__b351519144360">Authorization</strong> (signature information) and <strong id="lts_api_0004__b3515131483610">X-Sdk-Date</strong> (time when the request is sent) header fields are automatically added to the request.</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p1577123365010">For details, see "AK/SK-based Authentication" in <a href="lts_api_0005.html">Authentication</a>.</p>
|
|
</div></div>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p42118461957">The API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">obtain a user token</a> does not require authentication. Therefore, only the <strong id="lts_api_0004__b9332118172011">Content-Type</strong> field needs to be added to requests for calling the API. An example of such requests is as follows:</p>
|
|
</div>
|
|
<div class="section" id="lts_api_0004__en-us_topic_0192137669_section14612192315587"><h4 class="sectiontitle">Request Body (Optional)</h4><p id="lts_api_0004__en-us_topic_0192137669_en-us_topic_0113746487_p76011911717">This part is optional. A request body is often sent in a structured format (for example, JSON or XML) as defined in the <strong id="lts_api_0004__b4251143083713">Content-Type</strong> header field. All characters in a request body must be UTF-8 encoded.</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p1847214711331">The request body varies between APIs. Some APIs do not require the request body, such as the APIs requested using the GET and DELETE methods.</p>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p105261225101112">In the case of the API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">obtain a user token</a>, the request parameters and parameter description can be obtained from the API request. The following provides an example request with a body included. Replace <strong id="lts_api_0004__b9169184170"><em id="lts_api_0004__i416131831714">username</em></strong>, <strong id="lts_api_0004__b1161018101719"><em id="lts_api_0004__i101618182175">domainname</em></strong>, <strong id="lts_api_0004__b81721821715"><em id="lts_api_0004__i121791841716">******** </em></strong>(login password), and <strong id="lts_api_0004__b1817718131716"><em id="lts_api_0004__i11711871719">xxxxxxxxxxxxxxxxx</em></strong> (project name) with the actual values. Obtain a project name from <a href="https://docs.otc.t-systems.com/en-us/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
|
|
<div class="note" id="lts_api_0004__en-us_topic_0192137669_note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="lts_api_0004__en-us_topic_0192137669_p199011223194814">The <strong id="lts_api_0004__en-us_topic_0192137669_b319711645718">scope</strong> parameter specifies where a token takes effect. You can set <strong id="lts_api_0004__b16568153818256">scope</strong> to an account or a project under an account. For details, see <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">Obtaining a User Token</a>.</p>
|
|
</div></div>
|
|
<div class="codecoloring" codetype="Java" id="lts_api_0004__en-us_topic_0192137669_screen6140617194816"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
|
|
<span class="normal"> 2</span>
|
|
<span class="normal"> 3</span>
|
|
<span class="normal"> 4</span>
|
|
<span class="normal"> 5</span>
|
|
<span class="normal"> 6</span>
|
|
<span class="normal"> 7</span>
|
|
<span class="normal"> 8</span>
|
|
<span class="normal"> 9</span>
|
|
<span class="normal">10</span>
|
|
<span class="normal">11</span>
|
|
<span class="normal">12</span>
|
|
<span class="normal">13</span>
|
|
<span class="normal">14</span>
|
|
<span class="normal">15</span>
|
|
<span class="normal">16</span>
|
|
<span class="normal">17</span>
|
|
<span class="normal">18</span>
|
|
<span class="normal">19</span>
|
|
<span class="normal">20</span>
|
|
<span class="normal">21</span>
|
|
<span class="normal">22</span>
|
|
<span class="normal">23</span>
|
|
<span class="normal">24</span>
|
|
<span class="normal">25</span></pre></div></td><td class="code"><div><pre><span></span><span class="n">Content</span><span class="o">-</span><span class="n">Type</span><span class="p">:</span><span class="w"> </span><span class="n">application</span><span class="o">/</span><span class="n">json</span>
|
|
|
|
<span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"auth"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"identity"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"methods"</span><span class="p">:</span><span class="w"> </span><span class="o">[</span>
|
|
<span class="w"> </span><span class="s">"password"</span>
|
|
<span class="w"> </span><span class="o">]</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="s">"password"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"user"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"name"</span><span class="p">:</span><span class="w"> </span><span class="s">"username"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="s">"password"</span><span class="p">:</span><span class="w"> </span><span class="s">"********"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="s">"domain"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"name"</span><span class="p">:</span><span class="w"> </span><span class="s">"domainname"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">},</span>
|
|
<span class="w"> </span><span class="s">"scope"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"project"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="s">"name"</span><span class="p">:</span><span class="w"> </span><span class="s">"xxxxxxxxxxxxxxxxxx"</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre></div></td></tr></table></div>
|
|
</div>
|
|
<p id="lts_api_0004__en-us_topic_0192137669_p1859663401915">If all data required for the API request is available, you can send the request to call an API through <a href="https://curl.haxx.se/" target="_blank" rel="noopener noreferrer">curl</a>, <a href="https://www.getpostman.com/" target="_blank" rel="noopener noreferrer">Postman</a>, or coding. In the response to the API used to obtain a user token, <strong id="lts_api_0004__en-us_topic_0192137669_b5132934125612">x-subject-token</strong> is the desired user token. This token can then be used to authenticate the calling of other APIs.</p>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="lts_api_0003.html">Calling APIs</a></div>
|
|
</div>
|
|
</div>
|
|
|