doc-exports/docs/css/api-ref/css_03_0078.html
zhengxiu 6093788563 css api 20241120 version
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com>
Co-authored-by: zhengxiu <zhengxiu@huawei.com>
Co-committed-by: zhengxiu <zhengxiu@huawei.com>
2024-11-28 11:30:39 +00:00

150 lines
21 KiB
HTML

<a name="css_03_0078"></a><a name="css_03_0078"></a>
<h1 class="topictitle1">Making an API Request</h1>
<div id="body8662426"><p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p8141141101615">This section describes the structure of a RESTful API request, and uses the IAM API for obtain a user token as an example to describe how to call an API.</p>
<div class="section" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p729531715312">A request URI is in the following format:</p>
<p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p11610193811547"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_b3129104565416">{URI-scheme}://{<strong id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p19427155318264">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p11427453192617">Protocol used to transmit requests. All APIs use <strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b1111310119349">HTTPS</strong>.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0001.html#css_03_0001__section889174472415">Endpoints</a>. </p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p4427953122617">API access path for performing a specified operation. Obtain the value from the URI of an API. For example, the resource-path of the <span class="parmname" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_parmname663013436287"><b>API for obtaining a user token</b></span> is <span class="parmvalue" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_parmvalue176306433280"><b>/v3/auth/tokens</b></span>.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_parmname1718315019284"><b>Parameter name=Parameter value</b></span>". For example, <span class="parmname" id="css_03_0078__en-us_topic_0175865505_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>
<div class="p" id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_b156373055616">resource-path</strong> (<strong id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_screen14876158104020">https://&lt;iam-endpoint&gt;/v3/auth/tokens</pre>
</div>
<div class="note" id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_b316912223363">resource-path</strong> and a request method. The <strong id="css_03_0078__en-us_topic_0175865505_b1986350161720">URI-scheme</strong> of all APIs is HTTPS, and the endpoints of all APIs in the same region are identical.</p>
</div></div>
</div>
<div class="section" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_section580035055419"><h4 class="sectiontitle">Request Methods</h4><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_ul11356238151312"><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li1835819385137"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b12857113714364">GET</strong>: requests the server to return specified resources.</li><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li95631239131310"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b59328463362">PUT</strong>: requests the server to update specified resources.</li><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li1554910413138"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b2281114933619">POST</strong>: requests the server to add resources or perform special operations.</li><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li8237114421314"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b54061951103612">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li165331349151317"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b399416532361">HEAD</strong>: requests a server resource header.</li><li id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_li4440175411313"><strong id="css_03_0078__en-us_topic_0175865505_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_0078__p1345mcpsimp">For example, in the URI of the API for obtaining a user token, the request method is <strong id="css_03_0078__b12752137495596">POST</strong>. The request is as follows:</p>
<pre class="screen" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_screen1278712381542">
POST https://<em id="css_03_0078__en-us_topic_0175865505_i8606173611145">{iam-endpoint}</em>/v3/auth/tokens</pre>
</div>
<div class="section" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_section1454211155819"><h4 class="sectiontitle">Request Header</h4><p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p11811752397">You can also add additional fields to a request, such as the fields required by a specified URI or an HTTP method. For example, add <span class="parmname" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_parmname555313733714"><b>Content-Type</b></span> that defines a request body type to request for the authentication information.</p>
<p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p1467193205816"><a href="#css_03_0078__en-us_topic_0175865505_table181671338175614">Table 2</a> lists common request header fields.</p>
<div class="tablenoborder"><a name="css_03_0078__en-us_topic_0175865505_table181671338175614"></a><a name="en-us_topic_0175865505_table181671338175614"></a><table cellpadding="4" cellspacing="0" summary="" id="css_03_0078__en-us_topic_0175865505_table181671338175614" frame="border" border="1" rules="all"><caption><b>Table 2 </b>Common request headers</caption><thead align="left"><tr id="css_03_0078__en-us_topic_0175865505_row101671738165610"><th align="left" class="cellrowborder" valign="top" width="28.999999999999996%" id="mcps1.3.4.4.2.4.1.1"><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_p18168113813566">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="css_03_0078__en-us_topic_0175865505_row1496219145718"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_p1161017320119">Message body type (or format). You are advised to use the default value <span class="parmvalue" id="css_03_0078__parmvalue971413711257"><b>application/json</b></span>.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_row269463916566"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_p48391959195610">Mandatory for token authentication</p>
</td>
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0078__en-us_topic_0175865505_p108391599569">User token. It is the response to the API for obtaining a user token (only this API does not require authentication). After the request is processed, the value of <strong id="css_03_0078__b9545511335596">X-Subject-Token</strong> in the response header (Header) is the token value.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_row112831636205610"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_p12236100232">X-Project-Id</p>
</td>
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0078__en-us_topic_0175865505_p152363010314">No</p>
</td>
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0078__p19228496301">Subproject ID, which is used in multi-project scenarios. The <strong id="css_03_0078__b11423044585596">X-Project-ID</strong> field is mandatory in the request header for accessing resources in a subproject through AK/SK-based authentication.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_row1116873818569"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_p1168338205612">X-Sdk-Date</p>
</td>
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0078__en-us_topic_0175865505_p31687389562">Mandatory for AK/SK authentication</p>
</td>
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0078__p1930913752814">Request sending time. When AK/SK authentication is enabled, this field is automatically specified when SDK is used to sign the request.</p>
<p id="css_03_0078__p1175177122811">For details, see <a href="css_03_0079.html">Authentication</a>.</p>
<p id="css_03_0078__en-us_topic_0175865505_p15168173818564">The format is YYYYMMDD'T'HHMMSS'Z'. The value is the current GMT time of the system.</p>
</td>
</tr>
<tr id="css_03_0078__en-us_topic_0175865505_row21686380566"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_p1168338115620">Authorization</p>
</td>
<td class="cellrowborder" valign="top" width="25.94%" headers="mcps1.3.4.4.2.4.1.2 "><p id="css_03_0078__en-us_topic_0175865505_p2016933816564">Mandatory for AK/SK authentication</p>
</td>
<td class="cellrowborder" valign="top" width="45.06%" headers="mcps1.3.4.4.2.4.1.3 "><p id="css_03_0078__en-us_topic_0175865505_p3168173815567">Signature authentication information, When AK/SK authentication is enabled, this field is automatically specified when SDK is used to sign the request.</p>
<p id="css_03_0078__p1798716171610">For details, see <a href="css_03_0079.html">Authentication</a>.</p>
</td>
</tr>
<tr id="css_03_0078__row101581442131414"><td class="cellrowborder" valign="top" width="28.999999999999996%" headers="mcps1.3.4.4.2.4.1.1 "><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_p269715591239">Request language</p>
</td>
</tr>
</tbody>
</table>
</div>
<p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p42118461957">The API used to obtain a user token does not require authentication. Therefore, only the <span class="parmname" id="css_03_0078__en-us_topic_0175865505_parmname17151815123115"><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_0078__en-us_topic_0175865505_en-us_topic_0170917207_screen10131730155612">POST https://<em id="css_03_0078__en-us_topic_0175865505_i16184129191410">{iam-endpoint}</em>/v3/auth/tokens
Content-Type: application/json</pre>
</div>
<div class="section" id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_section14612192315587"><h4 class="sectiontitle">Request Body</h4><p id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_b1328019465393">Content-Type</strong>.</p>
<p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p1847214711331">The request body varies between APIs. Some APIs do not require the request body, such as the APIs requested using the <strong id="css_03_0078__b1772896188">GET</strong> and <strong id="css_03_0078__b1577313971810">DELETE</strong> methods.</p>
<p id="css_03_0078__en-us_topic_0175865505_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_0078__i20485545804559">username</em>, <em id="css_03_0078__i19765920364559">domainname</em>, <em id="css_03_0078__i10225544124559">********</em> (login password), and <em id="css_03_0078__i1957031724559">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_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p199011223194814">The <strong id="css_03_0078__en-us_topic_0175865505_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_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_screen6140617194816">POST https://<em id="css_03_0078__en-us_topic_0175865505_i1043451812139">{iam-endpoint}</em>/v3/auth/tokens
Content-Type: application/json
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "<em id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_i315217719194"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_b14500116161919">username</strong></em>", //Username
"password": "<strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_b2559181251918"><em id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_i12803128192">********</em></strong>", //Login password
"domain": {
"name": "<em id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_i1670713181171"><strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_b1332717181715">domainname</strong></em> " //Name of the account to which the user belongs
}
}
}
},
"scope": {
"project": {
"id": "<strong id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_b1261200101711"><em id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>" //Project ID
}
}
}
}</pre>
<p id="css_03_0078__en-us_topic_0175865505_en-us_topic_0170917207_en-us_topic_0168405763_p1859663401915">If all data required for the API request is available, you can send the request to call the API through curl, Postman, or coding. For the API of obtaining a user token, <strong id="css_03_0078__en-us_topic_0175865505_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_0077.html">Calling APIs</a></div>
</div>
</div>