vpruthi/doc-exports
1
0
Fork 0
forked from docs/doc-exports
Code Pull Requests Activity
doc-exports/docs/apiu/guidelines/apig-en-api-180328002.html
Chen, Junjie 97b6825626 APIU Guidelines 20240812 version 
Reviewed-by: Hasko, Vladimir <vladimir.hasko@t-systems.com>
Co-authored-by: Chen, Junjie <chenjunjie@huawei.com>
Co-committed-by: Chen, Junjie <chenjunjie@huawei.com>
2024-08-13 10:31:24 +00:00

194 lines
20 KiB
HTML
Raw Blame History

<a name="apig-en-api-180328002"></a><a name="apig-en-api-180328002"></a>
<h1 class="topictitle1">Overview of REST APIs</h1>
<div id="body1521440712463"><p id="apig-en-api-180328002__p351412010375">API Gateway provides RESTful APIs.</p>
<p id="apig-en-api-180328002__a43d1d1a130ea44338355338cae1cdf56">REST provides APIs to create, query, update, delete, and access service resources.</p>
<p id="apig-en-api-180328002__p662413466426">A REST API request/response pair is divided into the following parts:</p>
<ul id="apig-en-api-180328002__ul194283296595"><li id="apig-en-api-180328002__li542812955917">Request URI</li><li id="apig-en-api-180328002__li79271712549">Request method</li><li id="apig-en-api-180328002__li143901733185918">Request headers</li><li id="apig-en-api-180328002__li104621438155917">Request body</li><li id="apig-en-api-180328002__li1884574165914">Response headers</li><li id="apig-en-api-180328002__li132604765917">Response body</li></ul>
<div class="section" id="apig-en-api-180328002__section1849899574"><h4 class="sectiontitle">Request URI</h4><p id="apig-en-api-180328002__p729531715312">A request URI consists of the following parts:</p>
<p id="apig-en-api-180328002__p11610193811547"><strong id="apig-en-api-180328002__b3129104565416">{URI-scheme} :// {<strong id="apig-en-api-180328002__b10231116812">Endpoint</strong>} / {resource-path} ? {query-string}</strong></p>
<p id="apig-en-api-180328002__p19153141415558">Although a request URI is a part of 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="apig-en-api-180328002__t1797260c744a4e1a85d354f259cae55a" frame="border" border="1" rules="all"><caption><b>Table 1 </b>URI parameter description</caption><thead align="left"><tr id="apig-en-api-180328002__r6dceed05bcc649d2b032accbb2980a31"><th align="left" class="cellrowborder" valign="top" width="24.529999999999998%" id="mcps1.3.5.5.2.3.1.1"><p id="apig-en-api-180328002__a3446b6b785cb432bae9f45aef9177041">Parameter</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="75.47%" id="mcps1.3.5.5.2.3.1.2"><p id="apig-en-api-180328002__abe71244a12ac45308e99d4bbf975a9f8">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="apig-en-api-180328002__row106982018513"><td class="cellrowborder" valign="top" width="24.529999999999998%" headers="mcps1.3.5.5.2.3.1.1 "><p id="apig-en-api-180328002__p136991001517">URI-scheme</p>
</td>
<td class="cellrowborder" valign="top" width="75.47%" headers="mcps1.3.5.5.2.3.1.2 "><p id="apig-en-api-180328002__p56992017520">Protocol used to transmit the request.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__rb217758afff146a1b40b0dcbb28a4ae1"><td class="cellrowborder" valign="top" width="24.529999999999998%" headers="mcps1.3.5.5.2.3.1.1 "><p id="apig-en-api-180328002__en-us_topic_0035614179_p480227019422">Endpoint</p>
</td>
<td class="cellrowborder" valign="top" width="75.47%" headers="mcps1.3.5.5.2.3.1.2 "><p id="apig-en-api-180328002__ad82b3484a1be43ddadf436efbe15285e">Domain name or IP address of the server where the RESTful service endpoint is hosted. You can obtain the value from <a href="https://docs.otc.t-systems.com/regions-and-endpoints/index.html" target="_blank" rel="noopener noreferrer">Regions and Endpoints</a>.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__refeed61892004ea682639be281a1a707"><td class="cellrowborder" valign="top" width="24.529999999999998%" headers="mcps1.3.5.5.2.3.1.1 "><p id="apig-en-api-180328002__p1797614317513">resource-path</p>
</td>
<td class="cellrowborder" valign="top" width="75.47%" headers="mcps1.3.5.5.2.3.1.2 "><p id="apig-en-api-180328002__a90409cbb8b1c49c4ad4d3cfee16f475e">Path in which the resource requested by the API is located. The path is provided by the URI module of APIs, for example, <strong id="apig-en-api-180328002__b1491416539131">v3/auth/tokens</strong>.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row19939365518"><td class="cellrowborder" valign="top" width="24.529999999999998%" headers="mcps1.3.5.5.2.3.1.1 "><p id="apig-en-api-180328002__p393966455">Query string</p>
</td>
<td class="cellrowborder" valign="top" width="75.47%" headers="mcps1.3.5.5.2.3.1.2 "><p id="apig-en-api-180328002__p159401867517">This is an optional parameter. For example, the value can be the API version or resource selection criteria.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="apig-en-api-180328002__section580035055419"><h4 class="sectiontitle">Request Method</h4><p id="apig-en-api-180328002__p65661618145510">HTTP method: the type of requested operation.</p>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="apig-en-api-180328002__table26515221161" width="100%" frame="border" border="1" rules="all"><caption><b>Table 2 </b>HTTP methods supported</caption><thead align="left"><tr id="apig-en-api-180328002__row10728192251616"><th align="left" class="cellrowborder" valign="top" width="18%" id="mcps1.3.6.3.2.3.1.1"><p id="apig-en-api-180328002__p157281422201616">Method</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="82%" id="mcps1.3.6.3.2.3.1.2"><p id="apig-en-api-180328002__p672872219161">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="apig-en-api-180328002__row1394642154919"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p13848247114919">GET</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p2850147164917">Requests a server to provide a specified resource.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row5728322121617"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p97281922111616">PUT</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p1572882241617">Requests a server to update a specified resource.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row172872211168"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p472820225166">POST</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p272812212161">Requests a server to add resources or perform special operations.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row8728132231620"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p16729422151616">DELETE</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p10729122261616">Requests a server to delete a specified resource, for example, an object.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row2157183019175"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p15159030201715">HEAD</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p42261787492">Similar to the GET method, the HEAD method requests a server to provide the specified resource, but the server returns only the response header (excluding the response body) to this request.</p>
</td>
</tr>
<tr id="apig-en-api-180328002__row16729182210163"><td class="cellrowborder" valign="top" width="18%" headers="mcps1.3.6.3.2.3.1.1 "><p id="apig-en-api-180328002__p1772932218162">PATCH</p>
</td>
<td class="cellrowborder" valign="top" width="82%" headers="mcps1.3.6.3.2.3.1.2 "><p id="apig-en-api-180328002__p13729192251620">Requests a server to update a part of a specified resource.</p>
<p id="apig-en-api-180328002__p0729142221616">If the resource does not exist, the PATCH method may create a new resource.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="apig-en-api-180328002__section1454211155819"><h4 class="sectiontitle">Request Headers</h4><p id="apig-en-api-180328002__p155521124165511">Optional header fields: For example, such fields could be those required by a specified URI and HTTP method. <a href="#apig-en-api-180328002__t24b12299374a4f4ba9fbf5880aec2658">Table 3</a> describes common HTTP request header fields.</p>
<div class="tablenoborder"><a name="apig-en-api-180328002__t24b12299374a4f4ba9fbf5880aec2658"></a><a name="t24b12299374a4f4ba9fbf5880aec2658"></a><table cellpadding="4" cellspacing="0" summary="" id="apig-en-api-180328002__t24b12299374a4f4ba9fbf5880aec2658" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Common request headers</caption><thead align="left"><tr id="apig-en-api-180328002__r4c9188c98a9542db96d6d1aa49483890"><th align="left" class="cellrowborder" valign="top" width="20%" id="mcps1.3.7.3.2.5.1.1"><p id="apig-en-api-180328002__a0e8fe10f8be440a59cea60dfcef9d616">Header</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="27%" id="mcps1.3.7.3.2.5.1.2"><p id="apig-en-api-180328002__a0c5134defa3643d4a487a98564df4386">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="19%" id="mcps1.3.7.3.2.5.1.3"><p id="apig-en-api-180328002__a5e198cd1f1c84cd4a906d9afd43ee792">Remarks</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="34%" id="mcps1.3.7.3.2.5.1.4"><p id="apig-en-api-180328002__ac34a236127304521999242538b072c58">Example</p>
</th>
</tr>
</thead>
<tbody><tr id="apig-en-api-180328002__row10629133710114"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.3.7.3.2.5.1.1 "><p id="apig-en-api-180328002__p46301737411">Content-Type</p>
</td>
<td class="cellrowborder" valign="top" width="27%" headers="mcps1.3.7.3.2.5.1.2 "><p id="apig-en-api-180328002__p363011371216">Type (or format) of the message body.</p>
</td>
<td class="cellrowborder" valign="top" width="19%" headers="mcps1.3.7.3.2.5.1.3 "><p id="apig-en-api-180328002__p1263043712111">Mandatory</p>
</td>
<td class="cellrowborder" valign="top" width="34%" headers="mcps1.3.7.3.2.5.1.4 "><p id="apig-en-api-180328002__p13630183715110">application/json</p>
</td>
</tr>
<tr id="apig-en-api-180328002__r48b466a7608e4d6eb042a35f56cbdfb8"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.3.7.3.2.5.1.1 "><p id="apig-en-api-180328002__en-us_topic_0035614236_p792363911913">X-Auth-Token</p>
</td>
<td class="cellrowborder" valign="top" width="27%" headers="mcps1.3.7.3.2.5.1.2 "><p id="apig-en-api-180328002__p3237430121524">Token authentication information, which can be obtained by following the procedure in <a href="apig-en-api-180328003.html">Token Authentication</a>.</p>
</td>
<td class="cellrowborder" valign="top" width="19%" headers="mcps1.3.7.3.2.5.1.3 "><p id="apig-en-api-180328002__a1f6108d2189d4cd09376eebef87bb335">Mandatory if token authentication is used.</p>
</td>
<td class="cellrowborder" valign="top" width="34%" headers="mcps1.3.7.3.2.5.1.4 "><p id="apig-en-api-180328002__a993f118dde7d4c2f9164d578e9bc8c13">-</p>
</td>
</tr>
<tr id="apig-en-api-180328002__r0a259195cce44cee955af0a771a20d71"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.3.7.3.2.5.1.1 "><p id="apig-en-api-180328002__a4259b0099d3e432f88928e25c01d1127">X-Sdk-Date</p>
</td>
<td class="cellrowborder" valign="top" width="27%" headers="mcps1.3.7.3.2.5.1.2 "><p id="apig-en-api-180328002__abe5e383ccc8543c2aa4563830f67957a">Time at which the request was sent.</p>
</td>
<td class="cellrowborder" valign="top" width="19%" headers="mcps1.3.7.3.2.5.1.3 "><p id="apig-en-api-180328002__p1309136221732">Mandatory if AK/SK authentication is used.</p>
</td>
<td class="cellrowborder" valign="top" width="34%" headers="mcps1.3.7.3.2.5.1.4 "><p id="apig-en-api-180328002__a0f19b458af404df982f0dbb457a13925">20151222T034042Z</p>
</td>
</tr>
<tr id="apig-en-api-180328002__rc97d5ad8e26a47d9aadce68591dbbe62"><td class="cellrowborder" valign="top" width="20%" headers="mcps1.3.7.3.2.5.1.1 "><p id="apig-en-api-180328002__a7238e21480a841c7a1cbbbb21bdfc864">Authorization</p>
</td>
<td class="cellrowborder" valign="top" width="27%" headers="mcps1.3.7.3.2.5.1.2 "><p id="apig-en-api-180328002__p952592421823">Signature authentication information, which comes from the request signature result.</p>
</td>
<td class="cellrowborder" valign="top" width="19%" headers="mcps1.3.7.3.2.5.1.3 "><p id="apig-en-api-180328002__p865747321840">Mandatory if AK/SK authentication is used.</p>
</td>
<td class="cellrowborder" valign="top" width="34%" headers="mcps1.3.7.3.2.5.1.4 "><p id="apig-en-api-180328002__p608112012194">-</p>
<p id="apig-en-api-180328002__p20886442194"></p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="apig-en-api-180328002__section14612192315587"><h4 class="sectiontitle">Request Body (Optional)</h4><p id="apig-en-api-180328002__p23132011213">A request body conveys information other than the request header and is generally sent in a structured format (for example, JSON or XML) defined by the <strong id="apig-en-api-180328002__b12939183119235">Content-type</strong> field.</p>
</div>
<div class="section" id="apig-en-api-180328002__section7804143005810"><h4 class="sectiontitle">Response Headers</h4><p id="apig-en-api-180328002__p186593415539">A response header consists of an HTTP status code and additional response header fields.</p>
<ul id="apig-en-api-180328002__ul990954716531"><li id="apig-en-api-180328002__li7507195735313">HTTP status code: A status code consists of three digits (2xx to 5xx). 2xx indicates a success response. 4xx and 5xx indicate an error response. The status code returned can also be defined by the service.</li><li id="apig-en-api-180328002__li53801144205317">Optional header fields: For example, <strong id="apig-en-api-180328002__b2022915570239">Content-type</strong> could be one of such fields. <a href="#apig-en-api-180328002__tb5107e70c1d545de8b97ed913f602b83">Table 4</a> describes common response header fields.
<div class="tablenoborder"><a name="apig-en-api-180328002__tb5107e70c1d545de8b97ed913f602b83"></a><a name="tb5107e70c1d545de8b97ed913f602b83"></a><table cellpadding="4" cellspacing="0" summary="" id="apig-en-api-180328002__tb5107e70c1d545de8b97ed913f602b83" frame="border" border="1" rules="all"><caption><b>Table 4 </b>Response headers</caption><thead align="left"><tr id="apig-en-api-180328002__rf674063bc81649e8b9789a311a3bcf6e"><th align="left" class="cellrowborder" valign="top" width="23%" id="mcps1.3.9.3.2.3.2.4.1.1"><p id="apig-en-api-180328002__a4db082cf93e748d7b44040c488d0d38c">Header</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="44%" id="mcps1.3.9.3.2.3.2.4.1.2"><p id="apig-en-api-180328002__aa3e3c39e04e2407ea5bcda8fc61f112d">Description</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="33%" id="mcps1.3.9.3.2.3.2.4.1.3"><p id="apig-en-api-180328002__a53b16f94658d4903834e1c161d7759af">Example</p>
</th>
</tr>
</thead>
<tbody><tr id="apig-en-api-180328002__r471495aa79dc4a88a7110f2db9a835e3"><td class="cellrowborder" valign="top" width="23%" headers="mcps1.3.9.3.2.3.2.4.1.1 "><p id="apig-en-api-180328002__acebd9ce341d144b38d8674ad67443074">Date</p>
</td>
<td class="cellrowborder" valign="top" width="44%" headers="mcps1.3.9.3.2.3.2.4.1.2 "><p id="apig-en-api-180328002__a14609642298f4650890b08516c7db143">A standard HTTP header, which indicates the date and time when a message is sent. The format of this header field is defined in RFC 822.</p>
</td>
<td class="cellrowborder" valign="top" width="33%" headers="mcps1.3.9.3.2.3.2.4.1.3 "><p id="apig-en-api-180328002__ab1d152d4a35a4fbb86ed423b4b6d9bad">Mon, 12 Nov 2007 15:55:01 GMT</p>
</td>
</tr>
<tr id="apig-en-api-180328002__r0588e315fb784df790128bb6aecf61c9"><td class="cellrowborder" valign="top" width="23%" headers="mcps1.3.9.3.2.3.2.4.1.1 "><p id="apig-en-api-180328002__en-us_topic_0035614305_p306646695935">Server</p>
</td>
<td class="cellrowborder" valign="top" width="44%" headers="mcps1.3.9.3.2.3.2.4.1.2 "><p id="apig-en-api-180328002__a572e7868aa564539a661a36c8134adc4">A standard HTTP header, which contains the information about the software that the server uses to process requests.</p>
</td>
<td class="cellrowborder" valign="top" width="33%" headers="mcps1.3.9.3.2.3.2.4.1.3 "><p id="apig-en-api-180328002__afb122eb44b7446dd9a410167ac7c06ff">Apache</p>
</td>
</tr>
<tr id="apig-en-api-180328002__raa835d5c2e194ed19dc56366f0aedbe9"><td class="cellrowborder" valign="top" width="23%" headers="mcps1.3.9.3.2.3.2.4.1.1 "><p id="apig-en-api-180328002__a4bc2f8a7407b40329d7549814743dba4">Content-Length</p>
</td>
<td class="cellrowborder" valign="top" width="44%" headers="mcps1.3.9.3.2.3.2.4.1.2 "><p id="apig-en-api-180328002__a5db1494308504d32b0ed7464c14f3c91">A standard HTTP header, which indicates the size of the response body, in decimal number of bytes.</p>
</td>
<td class="cellrowborder" valign="top" width="33%" headers="mcps1.3.9.3.2.3.2.4.1.3 "><p id="apig-en-api-180328002__a016917505ad54f32bf5ae9e73c561ad2">xxx</p>
</td>
</tr>
<tr id="apig-en-api-180328002__rb4087468a73c487a84c136020cc4ef89"><td class="cellrowborder" valign="top" width="23%" headers="mcps1.3.9.3.2.3.2.4.1.1 "><p id="apig-en-api-180328002__ad6ed459cd4494fe1a0cbfe7988567c6f">Content-Type</p>
</td>
<td class="cellrowborder" valign="top" width="44%" headers="mcps1.3.9.3.2.3.2.4.1.2 "><p id="apig-en-api-180328002__ab38ec730e7b243d89e12ba173377ba37">A standard HTTP header, which specifies the media type of the response body sent to the recipient.</p>
</td>
<td class="cellrowborder" valign="top" width="33%" headers="mcps1.3.9.3.2.3.2.4.1.3 "><p id="apig-en-api-180328002__en-us_topic_0035614305_p940161295935">application/json</p>
</td>
</tr>
</tbody>
</table>
</div>
</li></ul>
</div>
<div class="section" id="apig-en-api-180328002__section034615592583"><h4 class="sectiontitle">Response Body (Optional)</h4><p id="apig-en-api-180328002__p133921631940">A response body conveys information other than the response header and is generally sent in a structured format (for example, JSON or XML) defined by the <strong id="apig-en-api-180328002__b18587619102713">Content-type</strong> field.</p>
</div>
<div class="section" id="apig-en-api-180328002__section140743661613"><h4 class="sectiontitle">Initiating Requests</h4><p id="apig-en-api-180328002__abe87411d02f441d8acf5a5f63d52edbe">A request can be initiated by using any of the following methods:</p>
<ul id="apig-en-api-180328002__u69bb0fd8d11a4e428f4e6fedc1515950"><li id="apig-en-api-180328002__la8e5f209e37b4c9eb0ae66f73d0ec1f0">cURL<p id="apig-en-api-180328002__a04f9f8ebd6674f36b25f63e65a92dcf2"><a name="apig-en-api-180328002__la8e5f209e37b4c9eb0ae66f73d0ec1f0"></a><a name="la8e5f209e37b4c9eb0ae66f73d0ec1f0"></a>cURL is a command line tool used to perform URL operations and transmit information. It serves as an HTTP client to send HTTP requests to the server and receive response messages. cURL is suitable for use in API tuning scenarios. For more information about cURL, visit <a href="https://curl.haxx.se/" target="_blank" rel="noopener noreferrer">https://curl.haxx.se/</a>.</p>
</li><li id="apig-en-api-180328002__lae3f7b6d508b43cd8565d0e8c4d9700b">Code<p id="apig-en-api-180328002__a02b0199016c4467693bc9cd4dcd9d74f"><a name="apig-en-api-180328002__lae3f7b6d508b43cd8565d0e8c4d9700b"></a><a name="lae3f7b6d508b43cd8565d0e8c4d9700b"></a>You can call APIs through code to assemble, send, and process requests.</p>
</li><li id="apig-en-api-180328002__l805ff59aa3f24f4ab7fbaa4962dd48e5">REST client<p id="apig-en-api-180328002__a26871275c663449488fffa9d8f492f51"><a name="apig-en-api-180328002__l805ff59aa3f24f4ab7fbaa4962dd48e5"></a><a name="l805ff59aa3f24f4ab7fbaa4962dd48e5"></a>Mozilla Firefox and Google Chrome provide a graphical browser plug-in for REST clients to send and process requests. For Mozilla Firefox, see <a href="https://addons.mozilla.org/en-US/firefox/addon/rest-client-apishub/" target="_blank" rel="noopener noreferrer">REST Client APIsHub</a>. For Google Chrome, see <a href="https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop" target="_blank" rel="noopener noreferrer">Postman</a>.</p>
</li></ul>
</div>
</div>
<div></div>
View Git Blame Copy Permalink