forked from docs/doc-exports
Chen, Junjie
7914103af1
Reviewed-by: Eotvos, Oliver <oliver.eotvos@t-systems.com> Co-authored-by: Chen, Junjie <chenjunjie@huawei.com> Co-committed-by: Chen, Junjie <chenjunjie@huawei.com>
96 lines
14 KiB
HTML
96 lines
14 KiB
HTML
<a name="functiongraph_06_0210"></a><a name="functiongraph_06_0210"></a>
|
|
|
|
<h1 class="topictitle1">Making an API Request</h1>
|
|
<div id="body60198535"><p id="functiongraph_06_0210__p187472011061">This section describes the structure of a REST API request, and uses the Identity and Access Management (IAM) API for <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.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="functiongraph_06_0210__en-us_topic_0091607286_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="functiongraph_06_0210__en-us_topic_0091607286_p729531715312">A request URI is in the following format:</p>
|
|
<p id="functiongraph_06_0210__en-us_topic_0091607286_p11610193811547"><strong id="functiongraph_06_0210__en-us_topic_0091607286_b3129104565416">{URI-scheme} :// {<strong id="functiongraph_06_0210__en-us_topic_0091607286_b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
|
|
<p id="functiongraph_06_0210__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>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="functiongraph_06_0210__en-us_topic_0113746487_table4443194632512" frame="border" border="1" rules="all"><caption><b>Table 1 </b>URI parameters</caption><thead align="left"><tr id="functiongraph_06_0210__en-us_topic_0113746487_row1944414616258"><th align="left" class="cellrowborder" valign="top" width="19.48%" id="mcps1.3.2.5.2.3.1.1"><p id="functiongraph_06_0210__en-us_topic_0113746487_p1644484692510">Parameter</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="80.52%" id="mcps1.3.2.5.2.3.1.2"><p id="functiongraph_06_0210__en-us_topic_0113746487_p174441146142511">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="functiongraph_06_0210__en-us_topic_0113746487_row10444144620259"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p154446465251">URI-scheme</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="80.52%" headers="mcps1.3.2.5.2.3.1.2 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p8444144692517">Protocol used to transmit requests. All APIs use <strong id="functiongraph_06_0210__b861464117015">HTTPS</strong>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="functiongraph_06_0210__en-us_topic_0113746487_row444414692513"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p7444194610257">Endpoint</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="80.52%" headers="mcps1.3.2.5.2.3.1.2 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p244474613259">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 Regions and Endpoints.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="functiongraph_06_0210__en-us_topic_0113746487_row1744454612520"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p14442468257">resource-path</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="80.52%" headers="mcps1.3.2.5.2.3.1.2 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p1844412467258">Resource path, that is, an API access path. Obtain the path from the URI of an API. For example, the <span class="parmname" id="functiongraph_06_0210__parmname0584125010013"><b>resource-path</b></span> of the API used to obtain a user token is <span class="parmvalue" id="functiongraph_06_0210__parmvalue15584185014016"><b>/v3/auth/tokens</b></span>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="functiongraph_06_0210__en-us_topic_0113746487_row184441346152515"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p4444154692516">query-string</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="80.52%" headers="mcps1.3.2.5.2.3.1.2 "><p id="functiongraph_06_0210__en-us_topic_0113746487_p1444414622514">Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "<em id="functiongraph_06_0210__i112484538014">Parameter name=Parameter value</em>". For example, <span class="parmname" id="functiongraph_06_0210__parmname124825320015"><b>?limit=10</b></span> indicates that a maximum of 10 data records will be displayed.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="note" id="functiongraph_06_0210__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="functiongraph_06_0210__en-us_topic_0091607286_p163316534416">To simplify the URI display in this document, each API is provided only with a <strong id="functiongraph_06_0210__b14305113319">resource-path</strong> and a request method. The <span class="parmname" id="functiongraph_06_0210__parmname91261914875"><b>URI-scheme</b></span> of all APIs is <span class="parmname" id="functiongraph_06_0210__parmname141319141711"><b>HTTPS</b></span>, and the endpoints of all APIs in the same region are identical.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="functiongraph_06_0210__section165852011162"><h4 class="sectiontitle">Request Methods</h4><p id="functiongraph_06_0210__p11750411667">The HTTP protocol defines the following request methods that can be used to send a request to the server:</p>
|
|
<ul id="functiongraph_06_0210__ul3750151118611"><li id="functiongraph_06_0210__li875010111562"><strong id="functiongraph_06_0210__b57718475463">GET</strong>: requests the server to return specified resources.</li><li id="functiongraph_06_0210__li375019111262"><strong id="functiongraph_06_0210__b7915175210469">PUT</strong>: requests the server to update specified resources.</li><li id="functiongraph_06_0210__li975051113611"><strong id="functiongraph_06_0210__b14200115584617">POST</strong>: requests the server to add resources or perform special operations.</li><li id="functiongraph_06_0210__li67509111766"><strong id="functiongraph_06_0210__b11515584461">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="functiongraph_06_0210__li3750161113617"><strong id="functiongraph_06_0210__b135232022473">HEAD</strong>: same as GET except that the server must return only the response header.</li><li id="functiongraph_06_0210__li87505111562"><strong id="functiongraph_06_0210__b15920176104713">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="functiongraph_06_0210__p47515111614">For example, in the case of the API used to <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtain a user token</a>, the request method is POST. The request is as follows:</p>
|
|
</div>
|
|
<div class="section" id="functiongraph_06_0210__section35948116619"><h4 class="sectiontitle">Request Header</h4><p id="functiongraph_06_0210__p475141112614">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 <strong id="functiongraph_06_0210__b84211134142911">Content-Type</strong>, which specifies the request body type.</p>
|
|
<p id="functiongraph_06_0210__p107511511463">Common request header fields are as follows:</p>
|
|
<ul id="functiongraph_06_0210__ul156821338131"><li id="functiongraph_06_0210__li16682153810319"><strong id="functiongraph_06_0210__b1663894024817">Content-Type</strong>: specifies the request body type or format. This field is mandatory and its default value is <strong id="functiongraph_06_0210__b6819193193012">application/json</strong>. Other values of this field will be provided for specific APIs if any.</li><li id="functiongraph_06_0210__li8682193819319"><strong id="functiongraph_06_0210__b17339153117388">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/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtain a user token</a>. This API is the only one that does not require authentication.</li></ul>
|
|
<div class="note" id="functiongraph_06_0210__note46211381434"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="functiongraph_06_0210__p166827384311">In addition to supporting token-based authentication, public cloud 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 <strong id="functiongraph_06_0210__b36691756103013">Authorization</strong> (signature information) and <strong id="functiongraph_06_0210__b2798101312">X-Sdk-Date</strong> (time when the request is sent) header fields are automatically added to the request.</p>
|
|
<p id="functiongraph_06_0210__p11682173813315">For more details, see .</p>
|
|
</div></div>
|
|
<ul id="functiongraph_06_0210__ul5682153816312"><li id="functiongraph_06_0210__li146820389315"><strong id="functiongraph_06_0210__b186687350523">X-Project-ID</strong>: specifies a subproject ID. This parameter is mandatory only in multi-project scenarios.</li><li id="functiongraph_06_0210__li1468215381137"><strong id="functiongraph_06_0210__b27019536523">X-Domain-ID</strong>: specifies an account ID.</li></ul>
|
|
<p id="functiongraph_06_0210__p67529119618">The API used to <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtain a user token</a> does not require authentication. Therefore, only the <strong id="functiongraph_06_0210__b1745213493313">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="functiongraph_06_0210__section10603171112616"><h4 class="sectiontitle">Request Body</h4><p id="functiongraph_06_0210__p475213111663">The body of a request is often sent in a structured format as specified in the <strong id="functiongraph_06_0210__b231611519018">Content-Type</strong> header field. The request body transfers content except the request header.</p>
|
|
<p id="functiongraph_06_0210__p875211119615">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="functiongraph_06_0210__p4752611167">In the case of the API used to <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.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 <em id="functiongraph_06_0210__i0360195816413">username</em>, <em id="functiongraph_06_0210__i13491160174213">domainname</em>, <em id="functiongraph_06_0210__i21743934210">********</em> (login password), and <em id="functiongraph_06_0210__i114471128421">xxxxxx</em> (project ID) with the actual values. To learn how to obtain a project ID, see Regions and Endpoints.</p>
|
|
<div class="note" id="functiongraph_06_0210__note1960413118616"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="functiongraph_06_0210__p197536111268">The <strong id="functiongraph_06_0210__b71948493510">scope</strong> parameter specifies where a token takes effect. You can set <strong id="functiongraph_06_0210__b209121413913">scope</strong> 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 section "Obtaining a User Token".</p>
|
|
</div></div>
|
|
<pre class="screen" id="functiongraph_06_0210__en-us_topic_0091607286_screen6140617194816">
|
|
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"auth": {
|
|
"identity": {
|
|
"methods": [
|
|
"password"
|
|
],
|
|
"password": {
|
|
"user": {
|
|
"name": "<em id="functiongraph_06_0210__en-us_topic_0091607286_i315217719194"><strong id="functiongraph_06_0210__en-us_topic_0091607286_b14500116161919">username</strong></em>",
|
|
"password": "<strong id="functiongraph_06_0210__en-us_topic_0091607286_b2559181251918"><em id="functiongraph_06_0210__en-us_topic_0091607286_i12803128192">********</em></strong>",
|
|
"domain": {
|
|
"name": "<em id="functiongraph_06_0210__en-us_topic_0091607286_i1560271681911"><strong id="functiongraph_06_0210__en-us_topic_0091607286_b17173191614194">domainname</strong></em>"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"scope": {
|
|
"project": {
|
|
"name": "<strong id="functiongraph_06_0210__en-us_topic_0091607286_b1261200101711"><em id="functiongraph_06_0210__en-us_topic_0091607286_i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>"
|
|
}
|
|
}
|
|
}
|
|
}</pre>
|
|
<p id="functiongraph_06_0210__p1225319222405"></p>
|
|
<p id="functiongraph_06_0210__p175320115613">If all data required for the API request is available, you can send the request to call the API through curl, <a href="https://www.getpostman.com/" target="_blank" rel="noopener noreferrer">Postman</a>, or coding. In the response to the API used to <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtain a user token</a>, <strong id="functiongraph_06_0210__b1417182271513">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="functiongraph_06_0200.html">Calling APIs</a></div>
|
|
</div>
|
|
</div>
|
|
|