doc-exports/docs/rds/api-ref/rds_03_0005.html

<a name="rds_03_0005"></a><a name="rds_03_0005"></a>

<h1 class="topictitle1">Making an API Request</h1>
<div id="body1565856735961"><p id="rds_03_0005__p15648656678">This section describes the structure of a REST API, 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 describe how to call an API. The obtained token is used to authenticate the calling of other APIs.</p>
<div class="section" id="rds_03_0005__en-us_topic_0113746487_section697653216219"><h4 class="sectiontitle">Request URI</h4><p id="rds_03_0005__en-us_topic_0113746487_p1327834192114">A request URI consists of the following:</p>
<p id="rds_03_0005__en-us_topic_0113746487_p015994616212"><strong id="rds_03_0005__en-us_topic_0113746487_b11186155382110">{URI-scheme}://{Endpoint}/{resource-path}?{query-string}</strong></p>
<p id="rds_03_0005__en-us_topic_0113746487_p16960034182113">Although a request URI is included in a request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message.</p>

<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="rds_03_0005__en-us_topic_0113746487_table4443194632512" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Parameters in a URI</caption><thead align="left"><tr id="rds_03_0005__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="rds_03_0005__en-us_topic_0113746487_p1644484692510"><strong id="rds_03_0005__b84235270618284">Parameter</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="80.52%" id="mcps1.3.2.5.2.3.1.2"><p id="rds_03_0005__en-us_topic_0113746487_p174441146142511"><strong id="rds_03_0005__b84235270611143">Description</strong></p>
</th>
</tr>
</thead>
<tbody><tr id="rds_03_0005__en-us_topic_0113746487_row10444144620259"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="rds_03_0005__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="rds_03_0005__en-us_topic_0113746487_p8444144692517">Protocol used to transmit requests. All APIs use HTTPS.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row444414692513"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="rds_03_0005__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="rds_03_0005__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 <a href="https://docs.otc.t-systems.com/en-us/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row1744454612520"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="rds_03_0005__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="rds_03_0005__en-us_topic_0113746487_p1844412467258">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="rds_03_0005__parmname10118203265616"><b>resource-path</b></span> of the API used to obtain a user token is <span class="parmvalue" id="rds_03_0005__parmvalue51182032175615"><b>/v3/auth/tokens</b></span>.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row184441346152515"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="rds_03_0005__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="rds_03_0005__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 "Parameter name=Parameter value". For example, <strong id="rds_03_0005__b1670793219241">? limit=10</strong> indicates that a maximum of 10 data records will be displayed.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note" id="rds_03_0005__note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="rds_03_0005__p163316534416">To simplify the URI display in this document, each API is provided only with a resource-path and a request method. The <strong id="rds_03_0005__b1635094325613">URI-scheme</strong> of all APIs is <strong id="rds_03_0005__b03511543105612">HTTPS</strong>, and the endpoints of all APIs in the same region are identical.</p>
</div></div>
</div>
<div class="section" id="rds_03_0005__en-us_topic_0113746487_section5296154118345"><h4 class="sectiontitle">Request Methods</h4><div class="p" id="rds_03_0005__p46347563325">The HTTP protocol defines the following request methods that can be used to send a request to the server:
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="rds_03_0005__en-us_topic_0113746487_table1961229113819" frame="border" border="1" rules="all"><caption><b>Table 2 </b>HTTP methods</caption><thead align="left"><tr id="rds_03_0005__en-us_topic_0113746487_row86141913816"><th align="left" class="cellrowborder" valign="top" width="30%" id="mcps1.3.3.2.1.2.3.1.1"><p id="rds_03_0005__en-us_topic_0113746487_p186147910387"><strong id="rds_03_0005__b84235270616346">Method</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="70%" id="mcps1.3.3.2.1.2.3.1.2"><p id="rds_03_0005__en-us_topic_0113746487_p166141293387"><strong id="rds_03_0005__b7106036145712">Description</strong></p>
</th>
</tr>
</thead>
<tbody><tr id="rds_03_0005__en-us_topic_0113746487_row146141194381"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="rds_03_0005__en-us_topic_0113746487_p12831539123914">GET</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.2.1.2.3.1.2 "><p id="rds_03_0005__en-us_topic_0113746487_p2831123916397">Requests the server to return specified resources.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row161429103817"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="rds_03_0005__en-us_topic_0113746487_p3831239183912">PUT</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.2.1.2.3.1.2 "><p id="rds_03_0005__en-us_topic_0113746487_p178311939193911">Requests the server to update specified resources.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row56141190384"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="rds_03_0005__en-us_topic_0113746487_p68311239113912">POST</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.2.1.2.3.1.2 "><p id="rds_03_0005__en-us_topic_0113746487_p1583133918391">Requests the server to add resources or perform special operations.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row861411903812"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="rds_03_0005__en-us_topic_0113746487_p1183153943916">DELETE</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.2.1.2.3.1.2 "><p id="rds_03_0005__en-us_topic_0113746487_p6831163914392">Requests the server to delete specified resources, for example, an object.</p>
</td>
</tr>
<tr id="rds_03_0005__en-us_topic_0113746487_row2614199163812"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="rds_03_0005__en-us_topic_0113746487_p1483143915390">PATCH</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.2.1.2.3.1.2 "><p id="rds_03_0005__en-us_topic_0113746487_p17831173918394">Requests the server to update partial content of a specified resource.</p>
<p id="rds_03_0005__en-us_topic_0113746487_p9831123911390">If the resource does not exist, a new resource will be created.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p id="rds_03_0005__p3759142614815">For example, in the case of the API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.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="rds_03_0005__section479119143310"><h4 class="sectiontitle">Request Header</h4><p id="rds_03_0005__p269363935616">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="rds_03_0005__en-us_topic_0170210613_en-us_topic_0170165298_parmname28091429124915"><b>Content-Type</b></span>, which specifies the request body type.</p>
<div class="p" id="rds_03_0005__p56967114331"><a href="#rds_03_0005__table1986821153312">Table 3</a> lists common request header fields.
<div class="tablenoborder"><a name="rds_03_0005__table1986821153312"></a><a name="table1986821153312"></a><table cellpadding="4" cellspacing="0" summary="" id="rds_03_0005__table1986821153312" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="rds_03_0005__row1286841153311"><th align="left" class="cellrowborder" valign="top" width="19.74%" id="mcps1.3.4.3.2.2.5.1.1"><p id="rds_03_0005__p178680183310"><strong id="rds_03_0005__b84235270691445">Name</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="26.5%" id="mcps1.3.4.3.2.2.5.1.2"><p id="rds_03_0005__p78688118335"><strong id="rds_03_0005__b16629161878">Description</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="20.11%" id="mcps1.3.4.3.2.2.5.1.3"><p id="rds_03_0005__p58686123316"><strong id="rds_03_0005__b1652015178718">Mandatory</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33.650000000000006%" id="mcps1.3.4.3.2.2.5.1.4"><p id="rds_03_0005__p48681314333"><strong id="rds_03_0005__b842352706103845">Example</strong></p>
</th>
</tr>
</thead>
<tbody><tr id="rds_03_0005__row1286861153311"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="rds_03_0005__p2086813163316">Host</p>
</td>
<td class="cellrowborder" valign="top" width="26.5%" headers="mcps1.3.4.3.2.2.5.1.2 "><p id="rds_03_0005__p58681814333">Specifies the requested server information, which can be obtained from the URL of the service API. The value is in the <em id="rds_03_0005__i19094210714">hostname[:port]</em> format. If the port number is not specified, the default port is used. The default port number for <strong id="rds_03_0005__b5371537315524">https</strong> is <strong id="rds_03_0005__b1367631015524">443</strong>.</p>
</td>
<td class="cellrowborder" valign="top" width="20.11%" headers="mcps1.3.4.3.2.2.5.1.3 "><p id="rds_03_0005__p886815123319">No</p>
<p id="rds_03_0005__p386811116333">This parameter is mandatory for AK/SK authentication.</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="rds_03_0005__p486814118330">code.test.com</p>
<p id="rds_03_0005__p5868161163317">or</p>
<p id="rds_03_0005__p786841123315">code.test.com:443</p>
</td>
</tr>
<tr id="rds_03_0005__row386818143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="rds_03_0005__p118689123320">Content-Type</p>
</td>
<td class="cellrowborder" valign="top" width="26.5%" headers="mcps1.3.4.3.2.2.5.1.2 "><p id="rds_03_0005__p1486815116337">Specifies the MIME type of the request body. You are advised to use the default value <strong id="rds_03_0005__en-us_topic_0121682347_b842352706171425">application/json</strong>. For APIs used to upload objects or images, the value can vary depending on the flow type.</p>
</td>
<td class="cellrowborder" valign="top" width="20.11%" headers="mcps1.3.4.3.2.2.5.1.3 "><p id="rds_03_0005__p1086812114335">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="rds_03_0005__p1186841163310">application/json</p>
</td>
</tr>
<tr id="rds_03_0005__row11868419337"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="rds_03_0005__p178687119330">Content-Length</p>
</td>
<td class="cellrowborder" valign="top" width="26.5%" headers="mcps1.3.4.3.2.2.5.1.2 "><p id="rds_03_0005__p178681813332">Specifies the length of the request body. The unit is byte.</p>
</td>
<td class="cellrowborder" valign="top" width="20.11%" headers="mcps1.3.4.3.2.2.5.1.3 "><p id="rds_03_0005__p18687183316">No</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="rds_03_0005__p148689110334">3495</p>
</td>
</tr>
<tr id="rds_03_0005__row2868171143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="rds_03_0005__p586815118338">X-Project-Id</p>
</td>
<td class="cellrowborder" valign="top" width="26.5%" headers="mcps1.3.4.3.2.2.5.1.2 "><p id="rds_03_0005__p1586811163312">Specifies the project ID. Obtain the project ID by following the instructions in <a href="rds_03_0002.html">Obtaining a Project ID</a>.</p>
</td>
<td class="cellrowborder" valign="top" width="20.11%" headers="mcps1.3.4.3.2.2.5.1.3 "><p id="rds_03_0005__p886812110335">No</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="rds_03_0005__p198684143315">e9993fc787d94b6c886cbaa340f9c0f4</p>
</td>
</tr>
<tr id="rds_03_0005__row188688113337"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="rds_03_0005__p198684111335">X-Auth-Token</p>
</td>
<td class="cellrowborder" valign="top" width="26.5%" headers="mcps1.3.4.3.2.2.5.1.2 "><p id="rds_03_0005__p1086851153317">Specifies the user token.</p>
<p id="rds_03_0005__p1057635831">The user token is a response to the API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">obtain a user token</a>. This API is the only one that does not require authentication.</p>
<p id="rds_03_0005__p15868417337">After the request is processed, the value of <strong id="rds_03_0005__b842352706205322">X-Subject-Token</strong> in the message header is the token value.</p>
</td>
<td class="cellrowborder" valign="top" width="20.11%" headers="mcps1.3.4.3.2.2.5.1.3 "><p id="rds_03_0005__p4868514338">No</p>
<p id="rds_03_0005__p986818114339">This parameter is mandatory for token authentication.</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="rds_03_0005__p27152505302">The following is part of an example token:</p>
<p id="rds_03_0005__p168689113318">MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p id="rds_03_0005__p42118461957">The API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.html" target="_blank" rel="noopener noreferrer">obtain a user token</a> does not require authentication. Therefore, only the <span class="parmname" id="rds_03_0005__parmname2074608145"><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>
</div>
<div class="section" id="rds_03_0005__en-us_topic_0113746487_section1437471411"><h4 class="sectiontitle">(Optional) Request Body</h4><p id="rds_03_0005__en-us_topic_0113746487_p76011911717">This part is optional. The body of a request is often sent in a structured format (for example, JSON or XML) as specified in the <strong id="rds_03_0005__b47491871565">Content-Type</strong> header field. If the request body contains full-width characters, these characters must be coded in UTF-8.</p>
<p id="rds_03_0005__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>
<div class="p" id="rds_03_0005__p105261225101112">In the case of the API used to <a href="https://docs.otc.t-systems.com/en-us/api/iam/en-us_topic_0057845583.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="rds_03_0005__i19326175117"><strong id="rds_03_0005__b183171711119">username</strong></em>, <em id="rds_03_0005__i4334179114"><strong id="rds_03_0005__b1533017516">domainname</strong></em>, <strong id="rds_03_0005__b9351017418"><em id="rds_03_0005__i163418177113">********</em></strong> (login password), and <strong id="rds_03_0005__b10361171719"><em id="rds_03_0005__i183617171411">xxxxxxxxxxxxxxxxxx</em></strong> (project name) with actual values. You can obtain the values from <a href="https://docs.otc.t-systems.com/en-us/endpoint/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.<div class="note" id="rds_03_0005__note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="rds_03_0005__p199011223194814">The <strong id="rds_03_0005__b13818161722011">scope</strong> parameter specifies where a token takes effect. You can set <strong id="rds_03_0005__b78485714154">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 <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>.</p>
</div></div>
</div>
<pre class="screen" id="rds_03_0005__screen18404136819">Content-Type: application/json

{
    "auth": {
        "identity": {
            "methods": [
                "password"
            ],
            "password": {
                "user": {
                    "name": "<em id="rds_03_0005__i13737202316812"><strong id="rds_03_0005__b177382231389">username</strong></em>",
                    "password": "<strong id="rds_03_0005__b1673802312811"><em id="rds_03_0005__i47381423788">********</em></strong>",
                    "domain": {
                        "name": "<em id="rds_03_0005__i17738923487"><strong id="rds_03_0005__b107385233815">domainname</strong></em>"
                    }
                }
            }
        },
        "scope": {
            "project": {
                "name": "<strong id="rds_03_0005__b373842313817"><em id="rds_03_0005__i973819231089">xxxxxxxxxxxxxxxxxx</em></strong>"
            }
        }
    }
}</pre>
<p id="rds_03_0005__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, <strong id="rds_03_0005__b107332287179">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="rds_02_0001.html">Calling APIs</a></div>
</div>
</div>