vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/ocr/api-ref/ocr_03_0002.html
Sheng, Lichang f0fbeaa320 OCR api 20240111 v2 
Reviewed-by: Pruthi, Vineet <vineet.pruthi@t-systems.com>
Co-authored-by: Sheng, Lichang <lichangsheng1@noreply.gitea.eco.tsi-dev.otc-service.com>
Co-committed-by: Sheng, Lichang <lichangsheng1@noreply.gitea.eco.tsi-dev.otc-service.com>
2024-01-17 10:01:47 +00:00

160 lines
15 KiB
HTML
Raw Blame History

<a name="ocr_03_0002"></a><a name="ocr_03_0002"></a>
<h1 class="topictitle1">Making an API Request</h1>
<div id="body0000001744422781"><p id="ocr_03_0002__p11567255145">This section describes the structure of a REST API request, and uses the API <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">for obtaining a user token</a> as an example to demonstrate how to call an API. The obtained token can then be used to authenticate the calling of other APIs.</p>
<div class="section" id="ocr_03_0002__section1227616904613"><h4 class="sectiontitle">Request URI</h4><p id="ocr_03_0002__p12406169184620">A request URI is in the following format:</p>
<p id="ocr_03_0002__p1640649114615"><strong id="ocr_03_0002__b540699104613">{URI-scheme} :// {Endpoint} / {resource-path} ? {query-string}</strong></p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="ocr_03_0002__table1285797467" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Request URI</caption><thead align="left"><tr id="ocr_03_0002__row10406109114618"><th align="left" class="cellrowborder" valign="top" width="18.18%" id="mcps1.3.2.4.2.3.1.1"><p id="ocr_03_0002__p114076914613">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="81.82000000000001%" id="mcps1.3.2.4.2.3.1.2"><p id="ocr_03_0002__p2040714919463">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="ocr_03_0002__row240715911466"><td class="cellrowborder" valign="top" width="18.18%" headers="mcps1.3.2.4.2.3.1.1 "><p id="ocr_03_0002__p19407797469">URI-scheme</p>
</td>
<td class="cellrowborder" valign="top" width="81.82000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="ocr_03_0002__p1140815918469">Protocol used to transmit requests. All APIs use <strong id="ocr_03_0002__b13695101115615">HTTPS</strong>.</p>
</td>
</tr>
<tr id="ocr_03_0002__row1140818924615"><td class="cellrowborder" valign="top" width="18.18%" headers="mcps1.3.2.4.2.3.1.1 "><p id="ocr_03_0002__p6408199114616">Endpoint</p>
</td>
<td class="cellrowborder" valign="top" width="81.82000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="ocr_03_0002__p640899104616">Domain name or IP address of the server for the REST service endpoint. The endpoint varies depending on services in different regions. It can be obtained in <a href="ocr_03_0062.html">Endpoint</a>.</p>
</td>
</tr>
<tr id="ocr_03_0002__row1740849184620"><td class="cellrowborder" valign="top" width="18.18%" headers="mcps1.3.2.4.2.3.1.1 "><p id="ocr_03_0002__p74084904616">resource-path</p>
</td>
<td class="cellrowborder" valign="top" width="81.82000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="ocr_03_0002__p174082994616">Access path of an API. Obtain the path from the URI of an API. For example, the <strong id="ocr_03_0002__b46644301465">resource-path</strong> of the API for obtaining a user token is <strong id="ocr_03_0002__b1266410304619">/v3/auth/tokens</strong>.</p>
</td>
</tr>
<tr id="ocr_03_0002__row240816994619"><td class="cellrowborder" valign="top" width="18.18%" headers="mcps1.3.2.4.2.3.1.1 "><p id="ocr_03_0002__p4408699465">query-string</p>
</td>
<td class="cellrowborder" valign="top" width="81.82000000000001%" headers="mcps1.3.2.4.2.3.1.2 "><p id="ocr_03_0002__p1408209154614">(Optional) Query parameter. Put a question mark (?) at the beginning. The format is <em id="ocr_03_0002__i1648934010618">Parameter name</em><strong id="ocr_03_0002__b10489640961">=</strong><em id="ocr_03_0002__i1248924019615">Parameter value</em>. For example, <strong id="ocr_03_0002__b194905407614">? limit=10</strong> indicates that a maximum of 10 data records will be displayed.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="note" id="ocr_03_0002__note95579334468"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="ocr_03_0002__p14558143312465">To simplify the URI display, each API is provided with only a <strong id="ocr_03_0002__b13697115010616">resource-path</strong> and a request method. All API URI schemes are HTTPS and the endpoints are the same in the same region.</p>
</div></div>
</div>
<div class="section" id="ocr_03_0002__section173058911469"><h4 class="sectiontitle">Request Method</h4><p id="ocr_03_0002__p1140812904620">HTTP defines the following request modes that can be used to send a request to the server:</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="ocr_03_0002__table3306169194614" frame="border" border="1" rules="all"><caption><b>Table 2 </b>HTTP methods</caption><thead align="left"><tr id="ocr_03_0002__row64083964619"><th align="left" class="cellrowborder" valign="top" width="30%" id="mcps1.3.3.3.2.3.1.1"><p id="ocr_03_0002__p5408139164610"><strong id="ocr_03_0002__b1840849104614">Method</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="70%" id="mcps1.3.3.3.2.3.1.2"><p id="ocr_03_0002__p124091799460"><strong id="ocr_03_0002__b34094916466">Description</strong></p>
</th>
</tr>
</thead>
<tbody><tr id="ocr_03_0002__row1840939134617"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p1640939204612">GET</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p1240959104620">Request the server to return a specific resource.</p>
</td>
</tr>
<tr id="ocr_03_0002__row18409159174620"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p340916904616">PUT</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p17409891469">Request the server to update a specific resource.</p>
</td>
</tr>
<tr id="ocr_03_0002__row84091097466"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p2409189204614">POST</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p184099918464">Request the server to create a new resource or perform a special operation.</p>
</td>
</tr>
<tr id="ocr_03_0002__row104090914614"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p7409109154612">DELETE</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p1640917913464">Request the server to delete a specific resource, such as an object.</p>
</td>
</tr>
<tr id="ocr_03_0002__row2409499466"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p74090954615">HEAD</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p34091934619">Request the server for the resource headers.</p>
</td>
</tr>
<tr id="ocr_03_0002__row6409179184619"><td class="cellrowborder" valign="top" width="30%" headers="mcps1.3.3.3.2.3.1.1 "><p id="ocr_03_0002__p44098910463">PATCH</p>
</td>
<td class="cellrowborder" valign="top" width="70%" headers="mcps1.3.3.3.2.3.1.2 "><p id="ocr_03_0002__p34101914614">Request the server to update a portion of the resource content.</p>
<p id="ocr_03_0002__p184100954619">PATCH may create a new resource if it does not exist.</p>
</td>
</tr>
</tbody>
</table>
</div>
<p id="ocr_03_0002__p54101393469">For example, if you use the POST method to obtain the URI of a user token, the request is as follows:</p>
<pre class="screen" id="ocr_03_0002__screen18410593466">POST https://<em id="ocr_03_0002__i114101911466">{iam-endpoint}</em>/v3/auth/tokens</pre>
</div>
<div class="section" id="ocr_03_0002__section2025265834813"><h4 class="sectiontitle">Request Header</h4><p id="ocr_03_0002__p1889533618497">You can add additional fields, for example, the fields required by a specified URI or HTTP method, to a request header. For example, add <span class="parmname" id="ocr_03_0002__parmname45287468118"><b>Content-Type</b></span>, which specifies the request body type, to a request for the authentication information.</p>
<p id="ocr_03_0002__p1489519365493"><a href="#ocr_03_0002__table2075523694911">Table 3</a> describes the common request header fields to be added to the request.</p>
<div class="tablenoborder"><a name="ocr_03_0002__table2075523694911"></a><a name="table2075523694911"></a><table cellpadding="4" cellspacing="0" summary="" id="ocr_03_0002__table2075523694911" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers </caption><thead align="left"><tr id="ocr_03_0002__row11895436134914"><th align="left" class="cellrowborder" valign="top" width="16.16161616161616%" id="mcps1.3.4.4.2.5.1.1"><p id="ocr_03_0002__p17895136154916">Header</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.3.4.4.2.5.1.2"><p id="ocr_03_0002__p1895436124911">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="20.202020202020204%" id="mcps1.3.4.4.2.5.1.3"><p id="ocr_03_0002__p489583614494">Mandatory</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="30.303030303030305%" id="mcps1.3.4.4.2.5.1.4"><p id="ocr_03_0002__p989533615497">Example</p>
</th>
</tr>
</thead>
<tbody><tr id="ocr_03_0002__row1089573615498"><td class="cellrowborder" valign="top" width="16.16161616161616%" headers="mcps1.3.4.4.2.5.1.1 "><p id="ocr_03_0002__p98961367493">Content-type</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.4.4.2.5.1.2 "><p id="ocr_03_0002__p2896103634910">Message body type (format). The default value is <span class="parmvalue" id="ocr_03_0002__parmvalue119165821975836"><b>application/json</b></span>.</p>
</td>
<td class="cellrowborder" valign="top" width="20.202020202020204%" headers="mcps1.3.4.4.2.5.1.3 "><p id="ocr_03_0002__p989643634918">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="30.303030303030305%" headers="mcps1.3.4.4.2.5.1.4 "><p id="ocr_03_0002__p1289653614912">application/json</p>
</td>
</tr>
<tr id="ocr_03_0002__row18961436104912"><td class="cellrowborder" valign="top" width="16.16161616161616%" headers="mcps1.3.4.4.2.5.1.1 "><p id="ocr_03_0002__p2896103684913">X-Auth-Token</p>
</td>
<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.3.4.4.2.5.1.2 "><p id="ocr_03_0002__p799663003710">User token</p>
<p id="ocr_03_0002__p59961430133710">Response for calling the <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> API. This API is the only one that does not require authentication. After the request is processed, the value of <strong id="ocr_03_0002__b114625830875836">X-Subject-Token</strong> in the response header (Header) is the token value.</p>
</td>
<td class="cellrowborder" valign="top" width="20.202020202020204%" headers="mcps1.3.4.4.2.5.1.3 "><p id="ocr_03_0002__p4896183624916">Mandatory for token-based authentication</p>
</td>
<td class="cellrowborder" valign="top" width="30.303030303030305%" headers="mcps1.3.4.4.2.5.1.4 "><p id="ocr_03_0002__p5710152813815">MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ</p>
</td>
</tr>
</tbody>
</table>
</div>
<p id="ocr_03_0002__p48661624114618">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, only the <strong id="ocr_03_0002__b13817135213579">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="ocr_03_0002__screen12603349164711">POST https://<em id="ocr_03_0002__i192291353204719">{iam-endpoint}</em>/v3/auth/tokens
Content-Type: application/json</pre>
</div>
<div class="section" id="ocr_03_0002__section10537104355514"><h4 class="sectiontitle">Request Body</h4><p id="ocr_03_0002__p16658117165412">The body of a request is often sent in a structured format (JSON or XML) as specified in the <strong id="ocr_03_0002__b14895148145817">Content-Type</strong> header field. The request body transfers content except the request header.</p>
<p id="ocr_03_0002__p1762282410524">For an API, the request parameters and parameter description are available in the request. The following provides an example request with a body included. Replace <em id="ocr_03_0002__i131531781175836">user_name</em>, <em id="ocr_03_0002__i81532801575836">domain_name</em>, <em id="ocr_03_0002__i86086425175836">********</em> (login password), and <em id="ocr_03_0002__i77570667375836">xxxxxxxx</em> (project ID) with the actual values. To learn how to obtain a project ID, see <a href="ocr_03_0130.html">Obtaining the Project ID</a>.</p>
<div class="note" id="ocr_03_0002__note1158072415522"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="ocr_03_0002__p16223246525">The <strong id="ocr_03_0002__b16718648115917">scope</strong> parameter specifies where a token takes effect. In the example, the token takes effect only for the resources in a specified project. OCR uses a region-specific endpoint to call this API. Set <strong id="ocr_03_0002__b96241154145915">scope</strong> to <strong id="ocr_03_0002__b36241546591">project</strong>. You can set <strong id="ocr_03_0002__b090616917018">scope</strong> to an account or a project under an account.</p>
</div></div>
<pre class="screen" id="ocr_03_0002__screen2622182411526">POST https://<em id="ocr_03_0002__i9622142465215">{iam-endpoint}</em>/v3/auth/tokens
Content-Type:application/json
{
"auth": {
"identity": {
"methods": ["password"],
"password": {
"user": {
"name": "<strong id="ocr_03_0002__b166235244521"><em id="ocr_03_0002__i12623924155216">user_name</em></strong>",
"password": "********",
"domain": {
"name": "<strong id="ocr_03_0002__b86231524145211"><em id="ocr_03_0002__i106231324175215">domain_name</em></strong>"
}
}
}
},
"scope": {
"project": {
"name": "xxxxxxxx"
}
}
}
}</pre>
<p id="ocr_03_0002__p16623624135212">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. <strong id="ocr_03_0002__b99896126114">x-subject-token</strong> in the response header 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="ocr_03_0001.html">API Calling</a></div>
</div>
</div>
View Git Blame Copy Permalink