vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/drs/api-ref/drs_01_0008.html
Ru, Li Yi f2556efa1c drs_api_20241121 
Reviewed-by: Gladkov, Maksim <mgladkov@noreply.gitea.eco.tsi-dev.otc-service.com>
Co-authored-by: Ru, Li Yi <liyiru7@huawei.com>
Co-committed-by: Ru, Li Yi <liyiru7@huawei.com>
2024-11-22 13:33:59 +00:00

183 lines
19 KiB
HTML
Raw Blame History

<a name="drs_01_0008"></a><a name="drs_01_0008"></a>
<h1 class="topictitle1">Making an API Request</h1>
<div id="body0000001072972321"><p id="drs_01_0008__en-us_topic_0117388899_p766319552332">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 requests for calling other APIs. </p>
<div class="section" id="drs_01_0008__en-us_topic_0117388899_section1171514171347"><h4 class="sectiontitle">Request URI</h4><p id="drs_01_0008__en-us_topic_0117388899_p2085151144410">A request URI consists of the following parts:</p>
<p id="drs_01_0008__en-us_topic_0117388899_p14851015444"><strong id="drs_01_0008__en-us_topic_0117388899_b58510114411">{URI-scheme}://{Endpoint}/{resource-path}?{query-string}</strong></p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="drs_01_0008__en-us_topic_0117388899_table1430135141120" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Request URI</caption><thead align="left"><tr id="drs_01_0008__en-us_topic_0117388899_row531155101117"><th align="left" class="cellrowborder" valign="top" width="19.67%" id="mcps1.3.2.4.2.3.1.1"><p id="drs_01_0008__en-us_topic_0117388899_p23119510112">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="80.33%" id="mcps1.3.2.4.2.3.1.2"><p id="drs_01_0008__en-us_topic_0117388899_p23110531110">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="drs_01_0008__en-us_topic_0117388899_row1731115181116"><td class="cellrowborder" valign="top" width="19.67%" headers="mcps1.3.2.4.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p331157116">URI-scheme</p>
</td>
<td class="cellrowborder" valign="top" width="80.33%" headers="mcps1.3.2.4.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p73113511112">Protocol used to transmit requests. All APIs use HTTPS.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row831175141111"><td class="cellrowborder" valign="top" width="19.67%" headers="mcps1.3.2.4.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p193145191116">Endpoint</p>
</td>
<td class="cellrowborder" valign="top" width="80.33%" headers="mcps1.3.2.4.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p33110551115">Domain name or IP address of the server bearing the REST service endpoint. Obtain the value from <a href="https://docs.otc.t-systems.com/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>. </p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row331155161111"><td class="cellrowborder" valign="top" width="19.67%" headers="mcps1.3.2.4.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p11318515111">resource-path</p>
</td>
<td class="cellrowborder" valign="top" width="80.33%" headers="mcps1.3.2.4.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p93116511116">API access path for performing a specified operation. Obtain the path from the URI of an API. For example, the <strong id="drs_01_0008__b22831349132118">resource-path</strong> of the API used to obtain a user token is <strong id="drs_01_0008__b1228914962111">/v3/auth/tokens</strong>.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row0311554117"><td class="cellrowborder" valign="top" width="19.67%" headers="mcps1.3.2.4.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p53112541116">query-string</p>
</td>
<td class="cellrowborder" valign="top" width="80.33%" headers="mcps1.3.2.4.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p73135151120">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, <strong id="drs_01_0008__en-us_topic_0117388899_b118042144320">? limit=10</strong> indicates that a maximum of 10 data records will be displayed.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="drs_01_0008__en-us_topic_0117388899_section198460447447"><h4 class="sectiontitle">Request Method</h4><p id="drs_01_0008__en-us_topic_0117388899_p6666452446">The HTTP protocol defines the following request methods that can be used to send a request to the server.</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="drs_01_0008__en-us_topic_0117388899_table691614731417" frame="border" border="1" rules="all"><caption><b>Table 2 </b>Request Method</caption><thead align="left"><tr id="drs_01_0008__en-us_topic_0117388899_row12917174713143"><th align="left" class="cellrowborder" valign="top" width="20.26%" id="mcps1.3.3.3.2.3.1.1"><p id="drs_01_0008__en-us_topic_0117388899_p891734710142">Method</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="79.74%" id="mcps1.3.3.3.2.3.1.2"><p id="drs_01_0008__en-us_topic_0117388899_p13917747101419">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="drs_01_0008__en-us_topic_0117388899_row39171147151417"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p79171547151412">GET</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p3917114791414">Requests a server to return specified resources.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row14917154717145"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p1891734721414">PUT</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p199171847101419">Requests a server to update specified resources.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row16917204719149"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p59171147161415">POST</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p14917204717141">Requests a server to add a resource or perform special operations.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row1091784741418"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p1691724713145">DELETE</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p16917647171411">Requests a server to delete specified resources, for example, an object.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row591774718149"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p129171547121420">HEAD</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p12917134712144">Same as GET except that the server must return only the response header.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row891724731413"><td class="cellrowborder" valign="top" width="20.26%" headers="mcps1.3.3.3.2.3.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p091718478145">PATCH</p>
</td>
<td class="cellrowborder" valign="top" width="79.74%" headers="mcps1.3.3.3.2.3.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p7917144701418">Requests a server to update partial content of a specified resource. If the resource does not exist, the PATCH method creates a resource.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p id="drs_01_0008__en-us_topic_0117388899_p18664454448">For example, in the case of the API used to obtain a user token, the request method is POST. The request is as follows:</p>
<div class="codecoloring" codetype="Java" id="drs_01_0008__screen7888377244"><div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div><pre><span></span><span class="n">POST</span><span class="w"> </span><span class="n">https</span><span class="p">:</span><span class="c1">//iam.eu-de.otc.t-systems.com/v3/auth/tokens</span>
</pre></div></td></tr></table></div>
</div>
</div>
<div class="section" id="drs_01_0008__en-us_topic_0117388899_section586724419442"><h4 class="sectiontitle">Request Headers</h4><p id="drs_01_0008__en-us_topic_0117388899_p1767645114415">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="drs_01_0008__en-us_topic_0117388899_parmname18298162017454"><b>Content-Type</b></span>, which specifies the request body type.</p>
<p id="drs_01_0008__en-us_topic_0117388899_p06764517440"><a href="#drs_01_0008__en-us_topic_0117388899_table1999891313010">Table 3</a> describes common request headers need to be added to requests.</p>
<div class="tablenoborder"><a name="drs_01_0008__en-us_topic_0117388899_table1999891313010"></a><a name="en-us_topic_0117388899_table1999891313010"></a><table cellpadding="4" cellspacing="0" summary="" id="drs_01_0008__en-us_topic_0117388899_table1999891313010" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="drs_01_0008__en-us_topic_0117388899_row999941311016"><th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.4.4.2.5.1.1"><p id="drs_01_0008__en-us_topic_0117388899_p49999132012">Name</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.4.4.2.5.1.2"><p id="drs_01_0008__en-us_topic_0117388899_p199911131604">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.4.4.2.5.1.3"><p id="drs_01_0008__en-us_topic_0117388899_p99994137018">Mandatory</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="25%" id="mcps1.3.4.4.2.5.1.4"><p id="drs_01_0008__en-us_topic_0117388899_p1799912130013">Example</p>
</th>
</tr>
</thead>
<tbody><tr id="drs_01_0008__en-us_topic_0117388899_row89999131804"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p385018241416">Content-Type</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p8850524018">Specifies the MIME type of the request body.</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.3 "><p id="drs_01_0008__en-us_topic_0117388899_p685019241117">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.4 "><p id="drs_01_0008__en-us_topic_0117388899_p885012245120">The default value is <strong id="drs_01_0008__en-us_topic_0117388899_b226610317479">application/json</strong>. Other values will be described in the specific APIs.</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row79991913701"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p0850122410117">Content-Length</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p118504248110">Length of the request body. The unit is byte.</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.3 "><ul id="drs_01_0008__en-us_topic_0117388899_ul98501224918"><li id="drs_01_0008__en-us_topic_0117388899_li28501424712">Optional for POST or PUT requests.</li><li id="drs_01_0008__en-us_topic_0117388899_li485010245118">Must be left blank for GET requests.</li></ul>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.4 "><p id="drs_01_0008__en-us_topic_0117388899_p108501924318">3495</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row17010141018"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p1850224219">X-Auth-Token</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p08503242115">Specifies a user token. This field is mandatory when token authentication is used. User token is a response to the API for obtaining a user token (only this API does not require authentication).</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.3 "><p id="drs_01_0008__en-us_topic_0117388899_p685052413114">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.4 "><p id="drs_01_0008__en-us_topic_0117388899_p285018241318">-</p>
</td>
</tr>
<tr id="drs_01_0008__en-us_topic_0117388899_row908147015"><td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.1 "><p id="drs_01_0008__en-us_topic_0117388899_p58506244115">X-Language</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.2 "><p id="drs_01_0008__en-us_topic_0117388899_p148508241313">Request language type.</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.3 "><p id="drs_01_0008__en-us_topic_0117388899_p13850182417117">No</p>
</td>
<td class="cellrowborder" valign="top" width="25%" headers="mcps1.3.4.4.2.5.1.4 "><p id="drs_01_0008__en-us_topic_0117388899_p1685092420113">en-us</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note" id="drs_01_0008__en-us_topic_0117388899_note924518121222"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="drs_01_0008__en-us_topic_0117388899_p1924617125215">For details about other headers, see the HTTP protocol.</p>
</div></div>
<p id="drs_01_0008__en-us_topic_0117388899_p9671745194411">The API used to obtain a user token does not require authentication. Therefore, only the <strong id="drs_01_0008__en-us_topic_0117388899_b106936455611">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="drs_01_0008__screen209011730183216">POST https://iam.eu-de.otc.t-systems.com/v3/auth/tokens
Content-Type: application/json</pre>
</div>
<div class="section" id="drs_01_0008__en-us_topic_0117388899_section8893944124416"><h4 class="sectiontitle">Request Body</h4><p id="drs_01_0008__en-us_topic_0117388899_p56724524418">The body of a request is often sent in a structured format as specified in the <strong id="drs_01_0008__en-us_topic_0117388899_b1328515795113">Content-Type</strong> header field. If the request body contains full-width characters, these characters must be coded in UTF-8.</p>
<p id="drs_01_0008__en-us_topic_0117388899_p86814458445">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="drs_01_0008__en-us_topic_0117388899_p468745174419">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 <strong id="drs_01_0008__en-us_topic_0117388899_b26804510441"><em id="drs_01_0008__i1668124524412">username</em></strong>, <strong id="drs_01_0008__en-us_topic_0117388899_b206817453444"><em id="drs_01_0008__i868144517447">domainname</em></strong>, <strong id="drs_01_0008__en-us_topic_0117388899_b14681745134410"><em id="drs_01_0008__i3684459443">********</em></strong> (login password), and <strong id="drs_01_0008__en-us_topic_0117388899_b953752813110"><em id="drs_01_0008__i653712814312">xxxxxxxxxx</em></strong> (project ID, for example, eu-de) with the actual values. To learn how to obtain a project ID, see <a href="https://docs.otc.t-systems.com/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
<div class="note" id="drs_01_0008__en-us_topic_0117388899_note13894114414413"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="drs_01_0008__en-us_topic_0117388899_p56812450446">The <strong id="drs_01_0008__en-us_topic_0117388899_b1233932217541">scope</strong> parameter specifies where a token takes effect. You can set <strong id="drs_01_0008__en-us_topic_0117388899_b8340152218543">scope</strong> to an account or a project under an account. You can set scope to an account or a project under an account. For details, see <a href="https://docs.otc.t-systems.com/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">Obtaining a User Token Through Password Authentication</a>.</p>
</div></div>
<pre class="screen" id="drs_01_0008__en-us_topic_0117388899_screen66874511446">
POST https://iam.eu-de.otc.t-systems.com/v3/auth/tokens
Content-Type: application/json
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "<strong id="drs_01_0008__en-us_topic_0117388899_b13681945184416"><em id="drs_01_0008__en-us_topic_0117388899_i146810458448">username</em></strong>",
"password": "<strong id="drs_01_0008__en-us_topic_0117388899_b11681345144418"><em id="drs_01_0008__en-us_topic_0117388899_i126812457441">********</em></strong>",
"domain": {
"name": "<strong id="drs_01_0008__en-us_topic_0117388899_b86804534418"><em id="drs_01_0008__en-us_topic_0117388899_i1668645164411">domainname</em></strong>"
}
}
}
},
"scope": {
"project": {
"name": "<strong id="drs_01_0008__en-us_topic_0117388899_b1069345184420"><em id="drs_01_0008__en-us_topic_0117388899_i1169145144417">xxxxxxxxxxxxxxxxxx</em></strong>"
}
}
}
}</pre>
<p id="drs_01_0008__en-us_topic_0117388899_p869144564416">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, <strong id="drs_01_0008__b1997452433610">x-subject-token</strong> is the desired user token. You can use the token to authenticate other API calls.</p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="drs_01_0004.html">Calling APIs</a></div>
</div>
</div>
View Git Blame Copy Permalink