forked from docs/doc-exports
Wei, Hongmin
c7cf8ac24f
Reviewed-by: Belejkanic, Lukas <lukas.belejkanic@t-systems.com> Co-authored-by: Wei, Hongmin <weihongmin1@huawei.com> Co-committed-by: Wei, Hongmin <weihongmin1@huawei.com>
105 lines
12 KiB
HTML
105 lines
12 KiB
HTML
<a name="iam_02_0008"></a><a name="iam_02_0008"></a>
|
|
|
|
<h1 class="topictitle1">Making an API Request</h1>
|
|
<div id="body1602512924297"><p id="iam_02_0008__p8141141101615">This section describes the structure of a REST API request, and uses the IAM API for obtaining a user token (see <a href="en-us_topic_0057845583.html">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="iam_02_0008__section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="iam_02_0008__p729531715312">A request URI is in the following format:</p>
|
|
<p id="iam_02_0008__p11610193811547"><strong id="iam_02_0008__b3129104565416">{URI-scheme} :// {<strong id="iam_02_0008__b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="iam_02_0008__table442645372610" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Parameter description</caption><thead align="left"><tr id="iam_02_0008__row15427253182617"><th align="left" class="cellrowborder" valign="top" width="18.790000000000003%" id="mcps1.3.2.4.2.3.1.1"><p id="iam_02_0008__p24271253182614">Parameter</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="81.21000000000001%" id="mcps1.3.2.4.2.3.1.2"><p id="iam_02_0008__p19427155318264">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="iam_02_0008__row104278530268"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="iam_02_0008__p44271053122619">URI-scheme</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="iam_02_0008__p11427453192617">Protocol used to transmit requests. All APIs use HTTPS.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="iam_02_0008__row1142745318267"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="iam_02_0008__p1342765311266">Endpoint</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="iam_02_0008__p164914501187">Domain name or IP address of the server bearing the REST service. The endpoint varies between services in different regions.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="iam_02_0008__row94271453112615"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="iam_02_0008__p144271753182618">resource-path</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="iam_02_0008__p4427953122617">Access path of an API for performing a specified operation. Obtain the path from the URI of an API. For example, the <span class="parmname" id="iam_02_0008__parmname79171115195313"><b>resource-path</b></span> of the API used to obtain a user token is <span class="parmvalue" id="iam_02_0008__parmvalue1992217159539"><b>/v3/auth/tokens</b></span>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="iam_02_0008__row1991179192817"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="iam_02_0008__p1091217918289">query-string</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="iam_02_0008__p79121799283">Query parameter, which is optional. Ensure that a question mark (?) is included before each query parameter that is in the format of "<em id="iam_02_0008__i75219985820">Parameter name</em>=<em id="iam_02_0008__i1052118913589">Parameter value</em>". For example, <strong id="iam_02_0008__b05217955819">?limit=10</strong> indicates that a maximum of 10 data records will be displayed.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<pre class="screen" id="iam_02_0008__screen1553450193818">
|
|
|
|
https://www.example.com/v3/auth/tokens</pre>
|
|
<div class="note" id="iam_02_0008__note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="iam_02_0008__p163316534416">To simplify the URI display in this document, each API is provided only with a <strong id="iam_02_0008__b1611016381912">resource-path</strong> and a request method. The <strong id="iam_02_0008__b1243511491819">URI-scheme</strong> of all APIs is <strong id="iam_02_0008__b2440114911115">HTTPS</strong>, and the endpoints of all APIs in the same region are identical.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="iam_02_0008__section580035055419"><h4 class="sectiontitle">Request Methods</h4><p id="iam_02_0008__p65661618145510">The HTTP protocol defines the following request methods that can be used to send a request to the server:</p>
|
|
<ul id="iam_02_0008__ul11356238151312"><li id="iam_02_0008__li1835819385137"><strong id="iam_02_0008__b1536117121621">GET</strong>: requests a server to return specified resources.</li><li id="iam_02_0008__li95631239131310"><strong id="iam_02_0008__b1239312113215">PUT</strong>: requests the server to update specified resources.</li><li id="iam_02_0008__li1554910413138"><strong id="iam_02_0008__b1292718223219">POST</strong>: requests the server to add resources or perform special operations.</li><li id="iam_02_0008__li8237114421314"><strong id="iam_02_0008__b33071632521">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="iam_02_0008__li165331349151317"><strong id="iam_02_0008__b77108361025">HEAD</strong>: same as GET except that the server must return only the response header.</li><li id="iam_02_0008__li4440175411313"><strong id="iam_02_0008__b126823536">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="iam_02_0008__p3759142614815">For example, in the case of the API used to obtain a user token (<a href="en-us_topic_0057845583.html">Obtaining a User Token</a>), the request method is POST. The request is as follows:</p>
|
|
<pre class="screen" id="iam_02_0008__screen1278712381542">
|
|
|
|
POST https://www.example.com/v3/auth/tokens</pre>
|
|
</div>
|
|
<div class="section" id="iam_02_0008__section1454211155819"><h4 class="sectiontitle">Request Header</h4><p id="iam_02_0008__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 <strong id="iam_02_0008__b55841429516">Content-Type</strong>, which specifies the request body type.</p>
|
|
<p id="iam_02_0008__p1467193205816">Common request header fields are as follows:</p>
|
|
<ul id="iam_02_0008__ul157293410593"><li id="iam_02_0008__li972916419595"><strong id="iam_02_0008__b767616141953">Content-Type</strong>: specifies the request body type or format. This field is mandatory and its default value is <span class="parmvalue" id="iam_02_0008__parmvalue166815143520"><b>application/json</b></span>.</li><li id="iam_02_0008__li1642421012595"><strong id="iam_02_0008__b197021132651">X-Auth-Token</strong>: specifies a user token only for token-based API authentication. <strong id="iam_02_0008__b191183531155">X-Auth-Token</strong> is a response to the API used to obtain a user token (<a href="en-us_topic_0057845583.html">Obtaining a User Token</a>). This API is the only one that does not require authentication.<div class="note" id="iam_02_0008__note13771123325011"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="iam_02_0008__p7838153812353">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 <strong id="iam_02_0008__b24331362610">Authorization</strong> (signature information) and <strong id="iam_02_0008__b843753618619">X-Sdk-Date</strong> (time when the request is sent) header fields are automatically added to the request.</p>
|
|
<p id="iam_02_0008__p083813833510">For details, see "AK/SK-based Authentication" in <a href="iam_02_0510.html">Authentication</a>.</p>
|
|
</div></div>
|
|
</li></ul>
|
|
<p id="iam_02_0008__p42118461957">The API used to obtain a user token (<a href="en-us_topic_0057845583.html">Obtaining a User Token</a>) does not require authentication. Only the <strong id="iam_02_0008__b196181520820">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="iam_02_0008__screen873519911458">
|
|
|
|
POST https://www.example.com/v3/auth/tokens
|
|
Content-Type: application/json</pre>
|
|
</div>
|
|
<div class="section" id="iam_02_0008__section14612192315587"><h4 class="sectiontitle">(Optional) Request Body</h4><p id="iam_02_0008__p23132011213">The body of a request is often sent in a structured format as specified in the <strong id="iam_02_0008__b15657727102318">Content-Type</strong> header field. The request body transfers content except the request header.</p>
|
|
<p id="iam_02_0008__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="iam_02_0008__p105261225101112">In the case of the API used to obtain a user token (<a href="en-us_topic_0057845583.html">Obtaining 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="iam_02_0008__i1490873516911">username</em>, <em id="iam_02_0008__i1691363515911">domainname</em>, <em id="iam_02_0008__i1491318351498">********</em> (login password), and <em id="iam_02_0008__i1091313351897">xxxxxxxxxxxxxxxxxx</em> (project ID) with the actual values. If you obtain a token using an account, ensure that you set <em id="iam_02_0008__i7487431193220">username</em> and <em id="iam_02_0008__i548723123214">domainname</em> to the same value.</p>
|
|
<div class="note" id="iam_02_0008__note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="iam_02_0008__p199011223194814">The <strong id="iam_02_0008__b673911551020">scope</strong> parameter specifies where a token takes effect. You can set <strong id="iam_02_0008__b07401650107">scope</strong> to an account or a project under the 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="en-us_topic_0057845583.html">Obtaining a User Token</a>.</p>
|
|
</div></div>
|
|
<pre class="screen" id="iam_02_0008__screen6140617194816">
|
|
|
|
POST https://www.example.com/v3/auth/tokens
|
|
Content-Type: application/json
|
|
|
|
{
|
|
"auth": {
|
|
"identity": {
|
|
"methods": [
|
|
"password"
|
|
],
|
|
"password": {
|
|
"user": {
|
|
"name": "<em id="iam_02_0008__i315217719194"><strong id="iam_02_0008__b14500116161919">username</strong></em>",
|
|
"password": "<strong id="iam_02_0008__b2559181251918"><em id="iam_02_0008__i12803128192">********</em></strong>",
|
|
"domain": {
|
|
"name": "<em id="iam_02_0008__i1560271681911"><strong id="iam_02_0008__b17173191614194">domainname</strong></em>"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"scope": {
|
|
"project": {
|
|
"id": "<strong id="iam_02_0008__b1261200101711"><em id="iam_02_0008__i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
<p id="iam_02_0008__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 (<a href="en-us_topic_0057845583.html">Obtaining a User Token</a>), <strong id="iam_02_0008__b1048815518105">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="iam_02_0000.html">Calling APIs</a></div>
|
|
</div>
|
|
</div>
|
|
|