vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/geminidb/api-ref/nosql_05_0008.html
Ru, Li Yi 37b97ffc06 geminidb_api 
Reviewed-by: Boka, Ladislav <ladislav.boka@t-systems.com>
Co-authored-by: Ru, Li Yi <liyiru7@huawei.com>
Co-committed-by: Ru, Li Yi <liyiru7@huawei.com>
2024-07-04 11:26:33 +00:00

172 lines
19 KiB
HTML
Raw Blame History

<a name="nosql_05_0008"></a><a name="nosql_05_0008"></a>
<h1 class="topictitle1">Making an API Request</h1>
<div id="body0000001354698224"><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_section697653216219"><h4 class="sectiontitle">Request URI</h4><p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p1327834192114">A request URI consists of the following:</p>
<p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p015994616212"><strong id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_b11186155382110">{URI-scheme}://{Endpoint}/{resource-path}?{query-string}</strong></p>
<p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p16960034182113">Although a request URI is included in the request header, most programming languages or frameworks require the request URI to be separately transmitted, rather than being conveyed in a request message separately.</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_table4443194632512" frame="border" border="1" rules="all"><caption><b>Table 1 </b>URI parameter description</caption><thead align="left"><tr id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p1644484692510">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="80.52%" id="mcps1.3.2.5.2.3.1.2"><p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p174441146142511">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row10444144620259"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p8444144692517">Protocol used to transmit requests. All APIs use HTTPS.</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row444414692513"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p244474613259">Domain name or IP address of the server bearing the REST service endpoint. The endpoint varies depending on services and 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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row1744454612520"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p1844412467258">Access path of an API for performing a specified operation. Obtain the path from the URI of the API. For example, the <span class="parmname" id="nosql_05_0008__parmname7592182514347"><b>resource-path</b></span> of the API for obtaining a user token is <span class="parmvalue" id="nosql_05_0008__parmvalue959352516344"><b>/v3/auth/tokens</b></span>.</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row184441346152515"><td class="cellrowborder" valign="top" width="19.48%" headers="mcps1.3.2.5.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__b474616120355">? limit=10</strong> indicates that up to 10 data records will be displayed.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_section5296154118345"><h4 class="sectiontitle">Request Methods</h4><div class="p" id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_table1961229113819" frame="border" border="1" rules="all"><caption><b>Table 2 </b>HTTP methods</caption><thead align="left"><tr id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p186147910387">Method</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="70%" id="mcps1.3.3.2.1.2.3.1.2"><p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p166141293387">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row146141194381"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p2831123916397">Requests a server to return specified resources.</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row161429103817"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p178311939193911">Requests a server to update specified resources.</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row56141190384"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p1583133918391">Requests a server to add a resource or perform a special operation.</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_row861411903812"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.2.1.2.3.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p6831163914392">Requests a server to delete a specified resource (for example, an object).</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p id="nosql_05_0008__en-us_topic_0121682347_p3759142614815">For example, in the URI for <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtaining a user token</a>, the request method is POST. The request is as follows:</p>
<pre class="screen" id="nosql_05_0008__en-us_topic_0121682347_screen7888377244">POST https://{{endpoint}}/v3/auth/tokens</pre>
</div>
<div class="section" id="nosql_05_0008__en-us_topic_0121682347_section479119143310"><h4 class="sectiontitle">Request Header</h4><p id="nosql_05_0008__en-us_topic_0121682347_p269363935616">You can also add additional header fields to a request, such as the fields required by a specified URI or HTTP method. For example, add <span class="parmname" id="nosql_05_0008__parmname1697132418117"><b>Content-Type</b></span> that defines a request body type to request for authentication information.</p>
<div class="p" id="nosql_05_0008__en-us_topic_0121682347_p56967114331"><a href="#nosql_05_0008__en-us_topic_0121682347_table1986821153312">Table 3</a> lists common request header fields.
<div class="tablenoborder"><a name="nosql_05_0008__en-us_topic_0121682347_table1986821153312"></a><a name="en-us_topic_0121682347_table1986821153312"></a><table cellpadding="4" cellspacing="0" summary="" id="nosql_05_0008__en-us_topic_0121682347_table1986821153312" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="nosql_05_0008__en-us_topic_0121682347_row1286841153311"><th align="left" class="cellrowborder" valign="top" width="19.74%" id="mcps1.3.4.3.2.2.5.1.1"><p id="nosql_05_0008__en-us_topic_0121682347_p178680183310">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="26.5%" id="mcps1.3.4.3.2.2.5.1.2"><p id="nosql_05_0008__en-us_topic_0121682347_p78688118335">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="20.11%" id="mcps1.3.4.3.2.2.5.1.3"><p id="nosql_05_0008__en-us_topic_0121682347_p58686123316">Mandatory</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33.650000000000006%" id="mcps1.3.4.3.2.2.5.1.4"><p id="nosql_05_0008__en-us_topic_0121682347_p48681314333">Example Value</p>
</th>
</tr>
</thead>
<tbody><tr id="nosql_05_0008__en-us_topic_0121682347_row386818143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_p1486815116337">MIME type of the request body. Use the default value <strong id="nosql_05_0008__b1455135481314">application/json</strong>. For APIs used to upload objects or images, the value varies 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="nosql_05_0008__en-us_topic_0121682347_p1086812114335">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="nosql_05_0008__en-us_topic_0121682347_p1186841163310">application/json</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_row11868419337"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_p178681813332">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="nosql_05_0008__en-us_topic_0121682347_p18687183316">This field is optional for POST requests, but must be left blank for GET requests.</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="nosql_05_0008__en-us_topic_0121682347_p148689110334">3495</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_row2868171143313"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_p1586811163312">Project ID. To obtain the project ID, see <a href="nosql_projectid.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="nosql_05_0008__en-us_topic_0121682347_p886812110335">No</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="nosql_05_0008__en-us_topic_0121682347_p198684143315">e9993fc787d94b6c886cbaa340f9c0f4</p>
</td>
</tr>
<tr id="nosql_05_0008__en-us_topic_0121682347_row188688113337"><td class="cellrowborder" valign="top" width="19.74%" headers="mcps1.3.4.3.2.2.5.1.1 "><p id="nosql_05_0008__en-us_topic_0121682347_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="nosql_05_0008__en-us_topic_0121682347_p1086851153317">User token.</p>
<p id="nosql_05_0008__en-us_topic_0121682347_p15868417337">After a request is processed, the value of <strong id="nosql_05_0008__b1621273813156">X-Subject-Token</strong> in the 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="nosql_05_0008__en-us_topic_0121682347_p4868514338">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="33.650000000000006%" headers="mcps1.3.4.3.2.2.5.1.4 "><p id="nosql_05_0008__en-us_topic_0121682347_p27152505302">The following is part of an example token:</p>
<p id="nosql_05_0008__en-us_topic_0121682347_p168689113318">MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p id="nosql_05_0008__en-us_topic_0121682347_p42118461957">The API used to <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtain a user token</a> does not require authentication. Therefore, this API only requires adding the <span class="parmname" id="nosql_05_0008__parmname19616135601517"><b>Content-Type</b></span> field. The following is an example request:</p>
<pre class="screen" id="nosql_05_0008__en-us_topic_0121682347_screen73731462616">POST https://{{endpoint}}/v3/auth/tokens
Content-Type: application/json</pre>
</div>
<div class="section" id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_section1437471411"><h4 class="sectiontitle">(Optional) Request Body</h4><p id="nosql_05_0008__en-us_topic_0121682347_en-us_topic_0113746487_p76011911717">This part is optional. The request body is often sent in a structured format (for example, JSON or XML) as specified in the <strong id="nosql_05_0008__b12517172619179">Content-Type</strong> header field. If the request body contains full-width characters, these characters must be coded in UTF-8.</p>
<p id="nosql_05_0008__en-us_topic_0121682347_p1847214711331">Request bodies vary depending on APIs. Some APIs do not require a request body, such as the APIs requested using the GET and DELETE methods.</p>
<p id="nosql_05_0008__en-us_topic_0121682347_p105261225101112">For the API of <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">obtaining a user token</a>, request parameters and parameter description can be obtained from the API request. The following is an example request with a body included. Replace <em id="nosql_05_0008__i169965417294">username</em>, <em id="nosql_05_0008__i8101135419294">domianname</em>, <em id="nosql_05_0008__i151010546295">********</em> (login password), and <em id="nosql_05_0008__i1210465413296">xxxxxxxxxxxxxxxxxx</em> (project name) with required 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>.</p>
<div class="note" id="nosql_05_0008__en-us_topic_0121682347_note15403511418"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="nosql_05_0008__en-us_topic_0121682347_p199011223194814">The <strong id="nosql_05_0008__b1638720387314">scope</strong> parameter specifies where a token takes effect. You can set <strong id="nosql_05_0008__b5388838163118">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 details, see <a href="https://docs.otc.t-systems.com/identity-access-management/api-ref/apis/token_management/obtaining_a_user_token.html" target="_blank" rel="noopener noreferrer">Obtaining a User Token</a>.</p>
</div></div>
<pre class="screen" id="nosql_05_0008__en-us_topic_0121682347_screen6140617194816">
POST https://{{endpoint}}/v3/auth/tokens
Content-Type: application/json
{
"auth": {
"identity": {
"methods": [
"password"
],
"password": {
"user": {
"name": "<em id="nosql_05_0008__en-us_topic_0121682347_i315217719194"><strong id="nosql_05_0008__en-us_topic_0121682347_b14500116161919">username</strong></em>",
"password": "<strong id="nosql_05_0008__en-us_topic_0121682347_b2559181251918"><em id="nosql_05_0008__en-us_topic_0121682347_i12803128192">********</em></strong>",
"domain": {
"name": "<em id="nosql_05_0008__en-us_topic_0121682347_i1560271681911"><strong id="nosql_05_0008__en-us_topic_0121682347_b17173191614194">domianname</strong></em>"
}
}
}
},
"scope": {
"project": {
"name": "<strong id="nosql_05_0008__en-us_topic_0121682347_b1261200101711"><em id="nosql_05_0008__en-us_topic_0121682347_i186128061711">xxxxxxxxxxxxxxxxxx</em></strong>"
}
}
}
}</pre>
<p id="nosql_05_0008__en-us_topic_0121682347_p1859663401915">If all data required for the API request is available, you can send a 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="nosql_05_0008__b10178125818346">x-subject-token</strong> in the response header is the required user token. Then, this token can 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="nosql_05_0007.html">Calling APIs</a></div>
</div>
</div>
View Git Blame Copy Permalink