forked from docs/doc-exports
Li, Qiao
dfe65b9551
Reviewed-by: Belejkanic, Lukas <lukas.belejkanic@t-systems.com> Co-authored-by: Li, Qiao <qiaoli@huawei.com> Co-committed-by: Li, Qiao <qiaoli@huawei.com>
71 lines
16 KiB
HTML
71 lines
16 KiB
HTML
<a name="kms_02_0001"></a><a name="kms_02_0001"></a>
|
|
|
|
<h1 class="topictitle1">Making an API Request</h1>
|
|
<div id="body32001227"><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p8141141101615">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="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p729531715312">A request URI is in the following format:</p>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p11610193811547"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b3129104565416">{URI-scheme} :// {<strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_ul1252522141910"><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li189491651174717"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b13950251174714">URI-scheme</strong>:<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p1697825294716">Protocol used to transmit requests. All APIs use HTTPS.</p>
|
|
</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li9112205519475"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b71122558472">Endpoint</strong>:<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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 the administrator.</p>
|
|
</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li370732114810"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b146431581502">resource-path</strong>:<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b41031934110">resource-path</strong> of the API used to obtain a user token is <span class="parmvalue" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmvalue10149384167"><b>/v3/auth/tokens</b></span>.</p>
|
|
</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li773319494816"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b1366984011119">query-string</strong>:<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p1727319564810">Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "Parameter name=Parameter value". For example, <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname10639423639"><b>?limit=10</b></span> indicates that a maximum of 10 data records will be displayed.</p>
|
|
</li></ul>
|
|
<div class="note" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p163316534416">To simplify the URI display in this document, each API is provided only with a <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname2744446171220"><b>resource-path</b></span> and a request method. The <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname1930591721317"><b>URI-scheme</b></span> of all APIs is <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname8102195251313"><b>HTTPS</b></span>, and the endpoints of all APIs in the same region are identical.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_section580035055419"><h4 class="sectiontitle">Request Methods</h4><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p65661618145510">The HTTP protocol defines the following request methods that can be used to send a request to the server:</p>
|
|
<ul id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_ul11356238151312"><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li1835819385137"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b134821659191217">GET</strong>: requests the server to return specified resources.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li95631239131310"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b13110121521312">PUT</strong>: requests the server to update specified resources.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li1554910413138"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b10756134061312">POST</strong>: requests the server to add resources or perform special operations.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li8237114421314"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b94535841311">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li165331349151317"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b139911817149">HEAD</strong>: same as GET except that the server must return only the response header.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li4440175411313"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b2820378146">PATCH</strong>: requests the server to update partial content of a specified resource. If the resource does not exist, a new resource will be created.</li></ul>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p3759142614815">For example, 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 method is POST. The request is as follows:</p>
|
|
<pre class="screen" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_screen7888377244">POST https://{{endpoint}}/v3/auth/tokens</pre>
|
|
</div>
|
|
<div class="section" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_section1454211155819"><h4 class="sectiontitle">Request Header</h4><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p11811752397">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="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname17561356151920"><b>Content-Type</b></span>, which specifies the request body type.</p>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p1467193205816">Common request header fields are as follows:</p>
|
|
<ul id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_ul157293410593"><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li972916419595"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b193861616191917">Content-Type</strong>: specifies the request body type or format. This field is mandatory and its default value is <span class="parmvalue" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmvalue87331219202115"><b>application/json</b></span>. Other values of this field will be provided for specific APIs if any.</li><li id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_li1642421012595"><strong id="kms_02_0001__en-us_topic_0171850909_b106124363150">X-Auth-Token</strong>: specifies a user token only for token-based API authentication. The user token is a response to 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>. This API is the only one that does not require authentication.<div class="note" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_note13771123325011"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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 the request, and the <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname20203125615277"><b>Authorization</b></span> (signature information) and <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname14331262816"><b>X-Sdk-Date</b></span> (time when the request is sent) header fields are automatically added to the request.</p>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p1577123365010">For more information, see .</p>
|
|
</div></div>
|
|
</li></ul>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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="kms_02_0001__en-us_topic_0171850909_b0253634097">Content-Type</strong> field needs to be added to requests for calling the API. An example of such requests is as follows:</p>
|
|
<pre class="screen" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_screen73731462616">POST https://{{endpoint}}/v3/auth/tokens
|
|
Content-Type: application/json</pre>
|
|
</div>
|
|
<div class="section" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_section14612192315587"><h4 class="sectiontitle">Request Body</h4><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p23132011213">The body of a request is often sent in a structured format as specified in the <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname8729201013377"><b>Content-Type</b></span> header field. The request body transfers content except the request header.</p>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_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. Set <em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i174716971020"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b44710910106">username</strong></em> to the name of a user, <em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i0988195621119"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b1598875611111">domainname</strong></em> to the name of the account that the user belongs to, <strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b181511322135"><em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i1615102161312">********</em></strong> to the user's login password, and <strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b628610137174"><em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i14286151318172">xxxxxxxxxxxxxxxxxx</em></strong> to the project name. You can learn more information about projects from .</p>
|
|
<div class="note" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p199011223194814">The <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname940418238457"><b>scope</b></span> parameter specifies where a token takes effect. You can set <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname145641316252"><b>scope</b></span> to an account or a project under an account. In the following example, the token takes effect only for the resources in a specified project. For more information about this API, 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>
|
|
<pre class="screen" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_screen6140617194816">
|
|
POST https://{{endpoint}}/v3/auth/tokens
|
|
Content-Type: application/json
|
|
{
|
|
"auth": {
|
|
"identity": {
|
|
"methods": [
|
|
"password"
|
|
],
|
|
"password": {
|
|
"user": {
|
|
"name": "<em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i315217719194"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b14500116161919">username</strong></em>",
|
|
"password": "<strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b2559181251918"><em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i12803128192">********</em></strong>",
|
|
"domain": {
|
|
"name": "<em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i1560271681911"><strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b17173191614194">domainname</strong></em>"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"scope": {
|
|
"project": {
|
|
"name": "<strong id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_b1261200101711"><em id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>"
|
|
}
|
|
}
|
|
}
|
|
}</pre>
|
|
<p id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_p1859663401915">If all data required for the API request is available, you can send the request to call the 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, <span class="parmname" id="kms_02_0001__en-us_topic_0171850909_en-us_topic_0091607286_parmname1744412247513"><b>x-subject-token</b></span> 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="kms_02_0002.html">Calling APIs</a></div>
|
|
</div>
|
|
</div>
|
|
|