vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/apig/api-ref/apig-api-180713011.html
Chen, Junjie 2fc8a34abd APIG API 20240125 version 
Reviewed-by: Bobkova, Natalia <natalia.bobkova@t-systems.com>
Co-authored-by: Chen, Junjie <chenjunjie@huawei.com>
Co-committed-by: Chen, Junjie <chenjunjie@huawei.com>
2024-10-25 11:19:06 +00:00

49 lines
16 KiB
HTML
Raw Permalink Blame History

<a name="apig-api-180713011"></a><a name="apig-api-180713011"></a>
<h1 class="topictitle1">Making an API Request</h1>
<div id="body8662426"><p id="apig-api-180713011__en-us_topic_0000001942519306_p49031951191414">This section describes the structure of a REST API request, and uses the APIG API for <strong id="apig-api-180713011__en-us_topic_0000001942519306_b1151719129413">creating an API group</strong> as an example to demonstrate how to call an API.</p>
<div class="section" id="apig-api-180713011__en-us_topic_0000001942519306_section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="apig-api-180713011__en-us_topic_0000001942519306_p729531715312">A request URI is in the following format:</p>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p11610193811547"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b3129104565416">{URI-scheme} :// {<strong id="apig-api-180713011__en-us_topic_0000001942519306_b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p19153141415558">Although a request URI is included in the request header, most programming languages or frameworks require the request URI to be transmitted separately.</p>
<ul id="apig-api-180713011__en-us_topic_0000001942519306_ul63581757356"><li id="apig-api-180713011__en-us_topic_0000001942519306_li183581756359"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b83920310421">URI-scheme</strong>: Protocol used to transmit requests. All APIs use <strong id="apig-api-180713011__en-us_topic_0000001942519306_b539313114215">HTTPS</strong>.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li16358958354"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b13517165134215">Endpoint</strong>: Domain name or IP address of the server bearing the REST service. It can be obtained from <a href="apig-api-190529263.html#apig-api-190529263__en-us_topic_0000001969180093_section932113578479">Endpoints</a>. .</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li53597512351"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b31682350472">resource-path</strong>: Access path of an API for performing a specified operation. Obtain the path from the URI of an API. For example, the <strong id="apig-api-180713011__en-us_topic_0000001942519306_b1029107104914">resource-path</strong> of the API used to create an API group is <strong id="apig-api-180713011__en-us_topic_0000001942519306_b9304774916">/v2/</strong><em id="apig-api-180713011__en-us_topic_0000001942519306_i4302710494">{project_id}</em><strong id="apig-api-180713011__en-us_topic_0000001942519306_b19304718494">/apigw/instances/</strong><em id="apig-api-180713011__en-us_topic_0000001942519306_i730187124915">{instance_id}</em><strong id="apig-api-180713011__en-us_topic_0000001942519306_b7304744915">/api-groups</strong>. <em id="apig-api-180713011__en-us_topic_0000001942519306_i73010716494">{project_id}</em> indicates a <a href="apig-api-180713009.html#apig-api-180713009">project ID</a> and <em id="apig-api-180713011__en-us_topic_0000001942519306_i113027154915">{instance_id}</em> indicates a gateway ID. The two IDs can be obtained from the gateway information on the APIG console.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li735905103516"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b133601140195112">query-string</strong>: Query parameter, which is optional. Ensure that a question mark (?) is included in front of each query parameter that is in the format of <em id="apig-api-180713011__en-us_topic_0000001942519306_i1558345512518">Parameter name</em><strong id="apig-api-180713011__en-us_topic_0000001942519306_b1558425515110">=</strong><em id="apig-api-180713011__en-us_topic_0000001942519306_i10584105516516">Parameter value</em>. For example, <strong id="apig-api-180713011__en-us_topic_0000001942519306_b458425545114">limit=10</strong> indicates that a maximum of 10 data records will be queried.</li></ul>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p1766380168">For example, if you want to create an API group in a region, set <strong id="apig-api-180713011__en-us_topic_0000001942519306_b17584171219398">URI-scheme</strong> to <strong id="apig-api-180713011__en-us_topic_0000001942519306_b3584141214395">HTTPS</strong>, <strong id="apig-api-180713011__en-us_topic_0000001942519306_b958451233915">Endpoint</strong> to <strong id="apig-api-180713011__en-us_topic_0000001942519306_b12984148114020">apig_endpoint</strong>, and <strong id="apig-api-180713011__en-us_topic_0000001942519306_b10584712183911">resource-path</strong> to <strong id="apig-api-180713011__en-us_topic_0000001942519306_b115841012193914">/v2/{project_id}/apigw/instances/{instance_id}/api-groups</strong>. Combine the parameters in the URI.</p>
<pre class="screen" id="apig-api-180713011__en-us_topic_0000001942519306_screen439264613101">https://<em id="apig-api-180713011__en-us_topic_0000001942519306_i16881440175117"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b198810405515">{apig_endpoint}</strong></em>/v2/{project_id}/apigw/instances/{instance_id}/api-groups</pre>
<div class="note" id="apig-api-180713011__en-us_topic_0000001942519306_note16311253154112"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="apig-api-180713011__en-us_topic_0000001942519306_p163316534416">To simplify the URI display in this document, each API is provided only with a <strong id="apig-api-180713011__en-us_topic_0000001942519306_b762314910439">resource-path</strong> and a request method. The <strong id="apig-api-180713011__en-us_topic_0000001942519306_b6118813104315">URI-scheme</strong> of all APIs is <strong id="apig-api-180713011__en-us_topic_0000001942519306_b7120913164319">HTTPS</strong>, and the endpoints of all APIs in the same region are identical.</p>
</div></div>
</div>
<div class="section" id="apig-api-180713011__en-us_topic_0000001942519306_section580035055419"><h4 class="sectiontitle">Request Method</h4><p id="apig-api-180713011__en-us_topic_0000001942519306_p65661618145510">The HTTP protocol defines the following request methods that can be used to send a request to the server:</p>
<ul id="apig-api-180713011__en-us_topic_0000001942519306_ul11356238151312"><li id="apig-api-180713011__en-us_topic_0000001942519306_li1835819385137"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b9892427436">GET</strong>: requests the server to return specified resources.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li95631239131310"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b118845234320">PUT</strong>: requests the server to update specified resources.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li1554910413138"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b8592953104312">POST</strong>: requests the server to add resources or perform special operations.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li8237114421314"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b814135613438">DELETE</strong>: requests the server to delete specified resources, for example, an object.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li165331349151317"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b21621019447">HEAD</strong>: same as GET except that the server must return only the response header.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li4440175411313"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b611035214447">PATCH</strong>: requests the server to update partial content of a specified resource. If the resource does not exist, a new resource will be created.</li></ul>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p3759142614815">For example, in the case of the API used to create an API group, the request method is POST. The request is as follows:</p>
<pre class="screen" id="apig-api-180713011__en-us_topic_0000001942519306_screen9521132712346">POST https://<em id="apig-api-180713011__en-us_topic_0000001942519306_i184832132513"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b20483013155120">{apig_endpoint}</strong></em>/v2/{project_id}/apigw/instances/{instance_id}/api-groups</pre>
</div>
<div class="section" id="apig-api-180713011__en-us_topic_0000001942519306_section1454211155819"><h4 class="sectiontitle">Request Header</h4><p id="apig-api-180713011__en-us_topic_0000001942519306_p11811752397">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 <strong id="apig-api-180713011__en-us_topic_0000001942519306_b8773171516475">Content-Type</strong>, which specifies the request body type.</p>
<div class="p" id="apig-api-180713011__en-us_topic_0000001942519306_p1467193205816">Common request header fields are as follows:<ul id="apig-api-180713011__en-us_topic_0000001942519306_ul572415371496"><li id="apig-api-180713011__en-us_topic_0000001942519306_li14724103714916"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b15753122315472">Content-Type</strong>: specifies the request body type or format. This field is mandatory and its default value is <strong id="apig-api-180713011__en-us_topic_0000001942519306_b17551623144714">application/json</strong>. Other values of this field will be provided for specific APIs if any.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li1724837494"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b1727203015472">X-Sdk-Date</strong>: specifies the time when a request is sent. This field is optional. When AK/SK authentication is enabled, this field is automatically specified when SDK is used to sign the request. For more information, see <a href="apig-api-190529268.html#apig-api-190529268__en-us_topic_0172440411_en-us_topic_0121671869_section0390282152">AK/SK-based Authentication</a>.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li207247371391"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b1367243719470">Authorization</strong>: specifies signature authentication information. This field is optional. When AK/SK authentication is enabled, this field is automatically specified when SDK is used to sign the request. For more information, see <a href="apig-api-190529268.html#apig-api-190529268__en-us_topic_0172440411_en-us_topic_0121671869_section0390282152">AK/SK-based Authentication</a>.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li67240371195"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b48241542154713">X-Auth-Token</strong>: specifies a user token only for token-based API authentication. The user token is a response to the API used to <strong id="apig-api-180713011__en-us_topic_0000001942519306_b13962393140">obtain a user token</strong>. This API is the only one that does not require authentication.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li472619372099"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b4381982410">X-Project-ID</strong>: specifies subproject ID. This field is optional and can be used in multi-project scenarios. The <strong id="apig-api-180713011__en-us_topic_0000001942519306_b19401131348">X-Project-ID</strong> field is mandatory in the request header for accessing resources in a sub-project through AK/SK-based authentication.</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li157261737995"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b171881115345">X-Domain-ID</strong>: specifies account ID, which is optional. When you call APIs of global services using AK/SK-based authentication, <strong id="apig-api-180713011__en-us_topic_0000001942519306_b8940193414">X-Domain-ID</strong> needs to be configured in the request header.</li></ul>
</div>
<div class="p" id="apig-api-180713011__en-us_topic_0000001942519306_p106812309215">If AK/SK authentication is used, the requests of the API used to create an API group with the added headers are as follows:<pre class="screen" id="apig-api-180713011__en-us_topic_0000001942519306_screen1462020111194">POST https://<em id="apig-api-180713011__en-us_topic_0000001942519306_i125614403501"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b956440135011">{apig_endpoint}</strong></em>/v2/{project_id}/apigw/instances/{instance_id}/api-groups
Content-Type: application/json
X-Sdk-Date: 20240416T095341Z
Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=****************</pre>
</div>
</div>
<div class="section" id="apig-api-180713011__en-us_topic_0000001942519306_section14612192315587"><h4 class="sectiontitle">Request Body</h4><p id="apig-api-180713011__en-us_topic_0000001942519306_p67501822253">The body of a request is often sent in a structured format as specified in <strong id="apig-api-180713011__en-us_topic_0000001942519306_b13211151817152">Content-Type</strong>. The request body transfers content other than the request header.</p>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p57506215250">Request bodies vary between APIs. Some APIs do not require the request body, such as the APIs requested using the <strong id="apig-api-180713011__en-us_topic_0000001942519306_b12519205617242">GET</strong> and <strong id="apig-api-180713011__en-us_topic_0000001942519306_b1953820586243">DELETE</strong> methods.</p>
<p id="apig-api-180713011__en-us_topic_0000001942519306_p675014215258">For the API used to create an API group, you can obtain the request parameters and parameter description from the API request. Here is an example request that includes a body. The bold fields must be configured as required.</p>
<ul id="apig-api-180713011__en-us_topic_0000001942519306_ul1558112914264"><li id="apig-api-180713011__en-us_topic_0000001942519306_li558192962612"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b10316276318">name</strong>: API group name</li><li id="apig-api-180713011__en-us_topic_0000001942519306_li125842952613"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b111225402313">remark</strong>: API group description</li></ul>
<pre class="screen" id="apig-api-180713011__en-us_topic_0000001942519306_screen6140617194816">POST https://<em id="apig-api-180713011__en-us_topic_0000001942519306_i4324529339"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b2325192915318">{apig_endpoint}</strong></em>/v2/{project_id}/v2/{project_id}/apigw/instances/{instance_id}/api-groups
Content-Type: application/json
X-Sdk-Date: 20240416T095341Z
Authorization: SDK-HMAC-SHA256 Access=****************, SignedHeaders=content-type;host;x-sdk-date, Signature=****************
{
"name": "<em id="apig-api-180713011__en-us_topic_0000001942519306_i169756514111"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b9704195118116">APIGroup_test</strong></em>",
"remark": "<em id="apig-api-180713011__en-us_topic_0000001942519306_i18129012171116"><strong id="apig-api-180713011__en-us_topic_0000001942519306_b133861359161113">api group remark</strong></em>"
}</pre>
<p id="apig-api-180713011__en-us_topic_0000001942519306_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.</p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="apig-api-180713003.html">Calling APIs</a></div>
</div>
</div>
View Git Blame Copy Permalink