forked from docs/doc-exports
Zheng, Xiu
3fa966049f
Reviewed-by: Kacur, Michal <michal.kacur@t-systems.com> Co-authored-by: Zheng, Xiu <zhengxiu@huawei.com> Co-committed-by: Zheng, Xiu <zhengxiu@huawei.com>
128 lines
17 KiB
HTML
128 lines
17 KiB
HTML
<a name="css_03_0138"></a><a name="css_03_0138"></a>
|
|
|
|
<h1 class="topictitle1">Making an API Request</h1>
|
|
<div id="body8662426"><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p8141141101615">This section describes the structure of a RESTful API request, and uses the API for Obtaining a User Token as an example to describe how to call an API. A token is a user's access credential, which contains the user identity and permission information. The obtained token is used to authenticate the calling of other APIs.</p>
|
|
<div class="section" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p729531715312">A request URI is in the following format:</p>
|
|
<p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p11610193811547"><strong id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_b3129104565416">{URI-scheme}://{<strong id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_b10231116812">Endpoint</strong>}/{resource-path}?{query-string}</strong></p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_table442645372610" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Request URL</caption><thead align="left"><tr id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_row15427253182617"><th align="left" class="cellrowborder" valign="top" width="18.790000000000003%" id="mcps1.3.2.4.2.3.1.1"><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_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="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p19427155318264">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_row104278530268"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p44271053122619">URI-scheme</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p11427453192617">Protocol used to transmit requests. All APIs use <strong id="css_03_0138__en-us_topic_0170917207_b1111310119349">HTTPS</strong>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_row1142745318267"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p1342765311266">Endpoint</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p64278534269">Domain name or IP address of the server running the REST service. The endpoint varies between services in different regions. It can be obtained from <a href="css_03_0053.html">Endpoints</a>. </p>
|
|
</td>
|
|
</tr>
|
|
<tr id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_row94271453112615"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p144271753182618">resource-path</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p4427953122617">API access path for performing a specified operation. Obtain the value from the URI of the API. For example, the <strong id="css_03_0138__en-us_topic_0170917207_b1671914773413">resource-path</strong> of the API for <span class="parmname" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_parmname663013436287"><b>obtaining a user token</b></span> is <span class="parmvalue" id="css_03_0138__en-us_topic_0170917207_parmvalue11721114710344"><b>/v3/auth/tokens</b></span>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_row1991179192817"><td class="cellrowborder" valign="top" width="18.790000000000003%" headers="mcps1.3.2.4.2.3.1.1 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p1091217918289">query-string</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="81.21000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p79121799283">Query parameter, which is optional. Ensure that a question mark (<span class="parmname" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_parmname5182450132811"><b>?</b></span>) is included before a query parameter that is in the format of "<span class="parmname" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_parmname1718315019284"><b>Parameter name=Parameter value</b></span>". For example, <span class="parmname" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_parmname818314500282"><b>limit=10</b></span> indicates that a maximum of 10 pieces of data is to be viewed.</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<pre class="screen" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_screen1553450193818"></pre>
|
|
<div class="p" id="css_03_0138__en-us_topic_0170917207_p61551914141610">For example, to obtain an IAM token in a region, obtain the endpoint of IAM for this region and the <strong id="css_03_0138__en-us_topic_0170917207_b156373055616">resource-path</strong> (<strong id="css_03_0138__en-us_topic_0170917207_b463770125619">/v3/auth/tokens</strong>) in the URI of the API used to obtain a user token. Then, construct the URI as follows:<pre class="screen" id="css_03_0138__screen14876158104020">https://<iam-endpoint>/v3/auth/tokens</pre>
|
|
</div>
|
|
<div class="note" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p163316534416">To simplify the URI display, each API is provided with only a <strong id="css_03_0138__en-us_topic_0170917207_b316912223363">resource-path</strong> and a request method. This is because the <strong id="css_03_0138__en-us_topic_0170917207_b17583726163618">URI-scheme</strong> value of all APIs is <strong id="css_03_0138__en-us_topic_0170917207_b8586826173614">HTTPS</strong>, and the endpoints in a region are the same. Therefore, the two parts are omitted.</p>
|
|
</div></div>
|
|
</div>
|
|
<div class="section" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_section580035055419"><h4 class="sectiontitle">Request Methods</h4><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p65661618145510">HTTP-based request methods, which are also called operations or actions, specify the type of operations that you are requesting.</p>
|
|
<ul id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_ul11356238151312"><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li1835819385137"><strong id="css_03_0138__en-us_topic_0170917207_b12857113714364">GET</strong>: requests the server to return specified resources.</li><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li95631239131310"><strong id="css_03_0138__en-us_topic_0170917207_b59328463362">PUT</strong>: requests the server to update specified resources.</li><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li1554910413138"><strong id="css_03_0138__en-us_topic_0170917207_b2281114933619">POST</strong>: requests the server to add resources or perform special operations.</li><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li8237114421314"><strong id="css_03_0138__en-us_topic_0170917207_b54061951103612">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li165331349151317"><strong id="css_03_0138__en-us_topic_0170917207_b399416532361">HEAD</strong>: requests a server resource header.</li><li id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_li4440175411313"><strong id="css_03_0138__en-us_topic_0170917207_b09452020375">PATCH</strong>: requests the server to update partial content of a specified resource. If the target resource does not exist, PATCH may create a resource.</li></ul>
|
|
<p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p3759142614815">If <strong id="css_03_0138__b2080910410304">POST</strong> is displayed in the URI of the API for obtaining a user token, the request is as follows:</p>
|
|
<pre class="screen" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_screen1278712381542">
|
|
POST https://<em id="css_03_0138__i8606173611145">{iam-endpoint}</em>/v3/auth/tokens</pre>
|
|
</div>
|
|
<div class="section" id="css_03_0138__section0359182216183"><h4 class="sectiontitle">Request Header</h4><p id="css_03_0138__p123591122141819">You can also add additional fields to a request, such as the fields required by a specified URI or an HTTP method. For example, to request for the authentication information, add <span class="parmname" id="css_03_0138__parmname632115153115"><b>Content-Type</b></span>, which specifies the request body type.</p>
|
|
<p id="css_03_0138__p10359522171815"><a href="#css_03_0138__table181671338175614">Table 2</a> lists common request header fields.</p>
|
|
|
|
<div class="tablenoborder"><a name="css_03_0138__table181671338175614"></a><a name="table181671338175614"></a><table cellpadding="4" cellspacing="0" summary="" id="css_03_0138__table181671338175614" frame="border" border="1" rules="all"><caption><b>Table 2 </b>Common request headers</caption><thead align="left"><tr id="css_03_0138__row101671738165610"><th align="left" class="cellrowborder" valign="top" width="28.999999999999996%" id="mcps1.3.4.4.2.4.1.1"><p id="css_03_0138__p71671738165620">Parameter</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="25.94%" id="mcps1.3.4.4.2.4.1.2"><p id="css_03_0138__p14168193875620">Mandatory</p>
|
|
</th>
|
|
<th align="left" class="cellrowborder" valign="top" width="45.06%" id="mcps1.3.4.4.2.4.1.3"><p id="css_03_0138__p18168113813566">Description</p>
|
|
</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr id="css_03_0138__row1496219145718"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0138__p146101031910">Content-Type</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0138__p14610103018">Yes</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0138__p1161017320119">Message body type (or format). You are advised to use the default value <strong id="css_03_0138__b335044313312">application/json</strong>.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="css_03_0138__row269463916566"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0138__p783917594568">X-Auth-Token</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0138__p48391959195610">No (Mandatory for token-based authentication)</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0138__p108391599569">User token.</p>
|
|
<p id="css_03_0138__p192053105915">Response for calling the "Obtaining a User Token" API. This API is the only one that does not require authentication. After the request is processed, the value of <strong id="css_03_0138__b83894564337">X-Subject-Token</strong> in the response header (Header) is the token value.</p>
|
|
</td>
|
|
</tr>
|
|
<tr id="css_03_0138__row3653847137"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0138__p17697145912311">X-Language</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0138__p369785915313">No</p>
|
|
</td>
|
|
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0138__p269715591239">Request language</p>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<p id="css_03_0138__p103591222161811">The API used to obtain a user token does not require authentication. Therefore, only the <span class="parmname" id="css_03_0138__parmname1912133113425"><b>Content-Type</b></span> field needs to be added to requests for calling the API. An example of such requests is as follows:</p>
|
|
<pre class="screen" id="css_03_0138__screen1236092214189">POST https://<em id="css_03_0138__i133601922141810">{iam-endpoint}</em>/v3/auth/tokens
|
|
Content-Type: application/json</pre>
|
|
</div>
|
|
<div class="section" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_section14612192315587"><h4 class="sectiontitle">Request Body</h4><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p23132011213">A request body conveys information other than the request header and is generally sent in a structured format defined by the request header field <strong id="css_03_0138__en-us_topic_0170917207_b1328019465393">Content-Type</strong>. </p>
|
|
<p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p1847214711331">The request body varies according to the APIs. Certain APIs do not require the request body, such as the GET and DELETE APIs.</p>
|
|
<p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p105261225101112">In the case of the API used to obtain a user token, 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="css_03_0138__i184231741104112">username</em>, <em id="css_03_0138__i12423164194115">domainname</em>, <em id="css_03_0138__i1042320419410">********</em> (login password), and <em id="css_03_0138__i194241041104118">xxxxxxxxxxxxxxxxxx</em> (project ID) with the actual values. To learn how to obtain a project ID, see <a href="css_03_0071.html">Obtaining a Project ID and Name</a>.</p>
|
|
<div class="note" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p199011223194814">The <strong id="css_03_0138__b341143183419">scope</strong> parameter defines the application scope of the token, indicating that the obtained token can access only the resources in the specified project.</p>
|
|
</div></div>
|
|
<pre class="screen" id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_screen6140617194816">POST https://<em id="css_03_0138__i1043451812139">{iam-endpoint}</em>/v3/auth/tokens
|
|
Content-Type: application/json
|
|
{
|
|
"auth": {
|
|
"identity": {
|
|
"methods": [
|
|
"password"
|
|
],
|
|
"password": {
|
|
"user": {
|
|
"name": "<em id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_i315217719194"><strong id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_b14500116161919">username</strong></em>", //Username
|
|
"password": "<strong id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_b2559181251918"><em id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_i12803128192">********</em></strong>", //Login password
|
|
"domain": {
|
|
"name": "<em id="css_03_0138__en-us_topic_0170917207_i1670713181171"><strong id="css_03_0138__en-us_topic_0170917207_b1332717181715">domainname</strong></em> " //Name of the account to which the user belongs
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"scope": {
|
|
"project": {
|
|
"id": "<strong id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_b1261200101711"><em id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>" //Project ID
|
|
}
|
|
}
|
|
}
|
|
}</pre>
|
|
<p id="css_03_0138__en-us_topic_0170917207_en-us_topic_0168405763_p1859663401915">If all data required by a 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. For the API of obtaining a user token, <strong id="css_03_0138__b1973816115516">x-subject-token</strong> in the response header is the desired user token. Then, you can use the token to authenticate the calling of other APIs.</p>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="css_03_0137.html">Calling APIs</a></div>
|
|
</div>
|
|
</div>
|
|
|