user guide (api calling) - developer-res-cbc-cn.obs.cn ...€¦ · api gateway user guide (api...

API Gateway

User Guide (API Calling)

Issue 07

Date 2018-08-31

HUAWEI TECHNOLOGIES CO., LTD.

Copyright © Huawei Technologies Co., Ltd. 2018. All rights reserved.No part of this document may be reproduced or transmitted in any form or by any means without prior writtenconsent of Huawei Technologies Co., Ltd. Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.All other trademarks and trade names mentioned in this document are the property of their respectiveholders. NoticeThe purchased products, services and features are stipulated by the contract made between Huawei and thecustomer. All or part of the products, services and features described in this document may not be within thepurchase scope or the usage scope. Unless otherwise specified in the contract, all statements, information,and recommendations in this document are provided "AS IS" without warranties, guarantees orrepresentations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in thepreparation of this document to ensure accuracy of the contents, but all statements, information, andrecommendations in this document do not constitute a warranty of any kind, express or implied.

Huawei Technologies Co., Ltd.Address: Huawei Industrial Base

Bantian, LonggangShenzhen 518129People's Republic of China

Website: http://www.huawei.com

Email: [email protected]

Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. i

http://www.huawei.com

mailto:[email protected]

Contents

1 Overview......................................................................................................................................... 1

2 API Gateway and Other Services............................................................................................... 2

3 Experiencing the Demo................................................................................................................ 3

4 Getting Started............................................................................................................................... 54.1 Overview........................................................................................................................................................................ 54.2 Obtaining an API and Its Documentation.......................................................................................................................64.3 (Optional) Creating an Application................................................................................................................................ 74.4 Calling an API................................................................................................................................................................ 84.5 Querying Information..................................................................................................................................................... 8

5 Application Management.......................................................................................................... 105.1 Creating an Application................................................................................................................................................105.2 Editing an Application.................................................................................................................................................. 115.3 Deleting an Application................................................................................................................................................125.4 Associating an Application with an API...................................................................................................................... 135.5 Resetting AppSecret..................................................................................................................................................... 145.6 Viewing API Details.....................................................................................................................................................145.7 Disassociating an Application from an API................................................................................................................. 15

6 SDK................................................................................................................................................ 16

7 Viewing Purchased APIs............................................................................................................17

8 Response Headers....................................................................................................................... 19

9 Error Codes................................................................................................................................... 21

10 Auditing...................................................................................................................................... 26

11 Monitoring.................................................................................................................................. 2711.1 API Gateway Metrics..................................................................................................................................................2711.2 Creating Alarm Rules................................................................................................................................................. 2711.3 Viewing Metrics..........................................................................................................................................................28

12 FAQs.............................................................................................................................................3012.1 How Is API Gateway Charged?..................................................................................................................................3012.2 What Are the Relationships Between an API, Environment, and App?.................................................................... 31

API GatewayUser Guide (API Calling) Contents

Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. ii

12.3 How Can I Use API Gateway?................................................................................................................................... 3112.4 Why Does a Backend Service Fail to Be invoked?.................................................................................................... 3112.5 What Is an Error Message Returned by API Gateway Like?..................................................................................... 3212.6 Do I Need to Publish an API Again After Modification?.......................................................................................... 3212.7 How Can I Protect My APIs?..................................................................................................................................... 3212.8 Can Mobile Applications Call APIs?......................................................................................................................... 3212.9 Can I Upload Files Using the POST Method?........................................................................................................... 3212.10 Can Applications Deployed in a VPC Call APIs?....................................................................................................3212.11 How Can I Ensure the Security of Backend Services Invoked by API Gateway?................................................... 3612.12 What SDK Languages Does API Gateway Support?...............................................................................................3612.13 How Can I Make an API Published in a Non-RELEASE Environment Accessible?..............................................3612.14 Does API Gateway Support Multiple Backend Endpoints?.....................................................................................3612.15 What Is the Maximum Size of an API Request Package?........................................................................................36

A What's New..................................................................................................................................37

API GatewayUser Guide (API Calling) Contents

Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. iii

1 Overview

API Gateway is a high-performance, high-availability, and high-security API hosting servicethat helps enterprises to build, manage, and deploy APIs at any scale. With just a few clicks,you can implement system integration, microservice aggregation, and serverless architectureswhile minimizing costs and risks.

API Gateway is suitable for diversified API opening scenarios. In addition to opening cloudservice capabilities of HUAWEI CLOUD, API Gateway enables you to enjoy secure,convenient, and efficient API services. Furthermore, API Gateway provides full API hostingservices, such as publishing, maintaining, and monitoring APIs, so that you can focus onservice development and quickly commercialize IT capabilities.

Figure 1-1 API Gateway overview

API GatewayUser Guide (API Calling) 1 Overview

Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 1

2 API Gateway and Other Services

Elastic Cloud Server (ECS)ECS allows you to obtain scalable cloud servers at any time. If your backend services aredeployed on ECS, you can use VPC links to access them without the need for ECS to enablepublic network access. This ensures network access security of the backend services. VPClinks support load balancing, which improves the response speed of ECS and reduces itspressure.

FunctionGraphFunctionGraph enables you to orchestrate service processes in a visualized manner, andcoordinates a series of function components to control service processes. API Gateway can beused as a trigger of the backend FunctionGraph. With an API Gateway trigger, computingfunctions can be invoked by calling APIs.

Cloud EyeCloud Eye is a secure, scalable monitoring platform in the public cloud. It monitors APIGateway service metrics, and sends notifications when alarms or events occur.

CTSCloud Trace Service (CTS) provides records of operations on cloud service resources,allowing you to query, audit, and backtrack the resource operation requests initiated from themanagement console or open APIs as well as responses to the requests.

API GatewayUser Guide (API Calling) 2 API Gateway and Other Services


3 Experiencing the Demo

Scenario

This demo shows how to use API Gateway to create and publish an API for querying mobilenumber home locations and associate a request throttling policy with the API with a fewclicks.

NOTE

If you want to experience the demo again, first delete the API and API group created in the demo.

Procedure

Step 1 Log in to the management console.

Step 2 Click in the upper left corner to select a region.

Step 3 In the service list, choose Application > API Gateway.

The navigation pane contains four columns: Dashboard, API Publishing, API Calling, andHelp Center.

Step 4 In the navigation pane, choose Dashboard.

Step 5 Click Experience Demo.

The system automatically performs the following operations:

l Creating an API group.

l Creating an API.

l Publishing the API in the RELEASE environment.

l Creating a request throttling policy.

l Associating the request throttling policy with the API.

Step 6 Click Call API.

Step 7 Enter a mobile number to be queried in the value column, click Send Request, and then viewthe return result.

API GatewayUser Guide (API Calling) 3 Experiencing the Demo


Step 8 Call the API.

1. Choose API Publishing > API Management, and click QueryPhoneNumber.

2. On the Monitoring tab page, click to copy the URL.

3. Paste the URL in the address bar of a browser, replace {phoneNumber} with a mobilenumber to be queried, and press Enter to view the home location of the mobile number.

----End

API GatewayUser Guide (API Calling) 3 Experiencing the Demo


4 Getting Started

Overview

Obtaining an API and Its Documentation

(Optional) Creating an Application

Calling an API

Querying Information

4.1 Overview

Preparations Before Calling an API

To call an API, you need to do the following:

1. Obtain the API and its documentation.– Obtain the API: Purchase the API from the cloud marketplace or obtain the API

through an offline channel, such as cooperation within the enterprise or betweenenterprises.

– Obtain the API documentation: The API provider provides reference documents inthe marketplace or through offline channels. The documents describe the requestand response parameters and examples of the API. If the API is provided byHUAWEI CLOUD, obtain reference documents from the HUAWEI CLOUD HelpCenter.

2. (Optional) Create an application.– For an API that is called using APP authentication, you need to create an

application to generate an application ID and key pair (AppKey and AppSecret).The API can be called using APP authentication only after it is bound with theapplication. During API calling, the key pair is replaced by that in the SDK, andAPI Gateway authenticates the identity of the API caller based on the key pair. Fordetails about APP authentication, see the API Gateway Developer Guide.

NOTE

Each API purchased from the marketplace comes with an application, so you do not need tocreate one again.

API GatewayUser Guide (API Calling) 4 Getting Started


https://support.huaweicloud.com/en-us/index.html


https://support.huaweicloud.com/en-us/devg-apig/apig-en-dev-180307002.html

– For an API that is called using NONE or IAM authentication, you do not need tocreate any application.

3. (Optional) Obtain authorization.– For an API that is published to the marketplace, you can obtain authorization of the

API and call it once you purchase it.– For an API that is not published to the marketplace and is accessed using APP

authentication, you need to provide your application information to the APIprovider to obtain authorization.

– For an API that is called using NONE or IAM authentication, you do not need toobtain authorization.

4. Call the API.After completing the preceding preparations, call the API by following the instructionsin Calling an API.

NOTE

API Gateway transfers the user IP address in the request packet header to backend services by default. Ifthe user IP address is private or sensitive information, the API developer should provide privacystatement to the API caller.

API Calling Process

The following figure illustrates the process of calling an API that is accessed using APPauthentication.

NOTE

An API purchased from the marketplace comes with an application and has been bound with it, so youcan directly call the API after purchasing.

The following figure illustrates the process of calling an API that is accessed using NONE orIAM authentication.

4.2 Obtaining an API and Its DocumentationObtain an API.

l Purchase an API from the marketplace.l Obtain an API through an offline channel, such as cooperation within an enterprise or

between enterprises.

Obtain the API documentation.

l For an API that is published to the marketplace, obtain the API reference documentsfrom the marketplace.



l For an API that is not published in the marketplace, contact the API provider to obtainthe API reference documents.

l If the API is provided by HUAWEI CLOUD, obtain reference documents from theHUAWEI CLOUD Help Center.

4.3 (Optional) Creating an Application

Scenario

For an API that is called using APP authentication, you need to create an application togenerate an application ID and key pair (AppKey and AppSecret). The API can be calledusing APP authentication only after it is bound with the application. During API calling, thekey pair is replaced by that in the SDK, and API Gateway authenticates the identity of theAPI caller based on the key pair. For details about APP authentication, see the API GatewayDeveloper Guide.

NOTE

l Each API purchased from the marketplace comes with an application, so you do not need to createone again.

l For an API that is called using NONE or IAM authentication, you do not need to create anyapplication.

l You can create a maximum of 50 applications. The application quota includes applications createdby you and those generated after you purchase APIs from the API marketplace.

Procedure




Step 4 Choose API Calling > Application Management.

Step 5 Click Create Application. On the Create Application page, set the parameters listed inTable 4-1.

Table 4-1 Application information

Parameter Description Value

ApplicationName

Name of the application l Must start with a letter.l Can contain letters,

digits, and underscores(_).

l Consists of 3 to 64characters.

Description Description of the application The value can contain 0–255 characters.






Step 6 Click OK.

The application and its ID are displayed in the application list on the ApplicationManagement page.

Step 7 Click the application name, and view the AppKey and AppSecret on the application detailspage.

----End

4.4 Calling an APIAPI Gateway provides multiple authentication modes for API callers to call APIs.

l NONE or IAM (token): SDKs are not required to access APIs.l APP and IAM (AK/SK): SDKs are required to access APIs.

SDKs in Java, Go, Python, JavaScript, C#, PHP, C++, and C are supported for API access.

For details about API calling, see the API Gateway Developer Guide.

4.5 Querying InformationYou can query application information (such as application names and IDs) and APIinformation (such as the API group to which the purchased APIs belong and the list ofpurchased APIs).

To help you quickly find required information on the API Gateway console, Table 4-2 liststhe information query indexes.

NOTE

The following information may be found in different transactions on the API Gateway console. Onlyone of them is listed.

Table 4-2 Key information query indexes

Category ConsolePath

Key Information Description

Application details

API Calling >ApplicationManagement> Applicationname

Application name Name of the application

Application ID Unique ID allocated to theapplication




Category ConsolePath

Key Information Description

AppKey Part of the key generated duringapplication creation. It is used tocalculate the verification value whenthe API is invoked. After receivingan API request, API Gateway checkscorrectness of the verification valueand completes identity authentication.

AppSecret Part of the key generated duringapplication creation. It is used tocalculate the verification value whenthe API is invoked. After receivingan API request, API Gateway checkscorrectness of the verification valueand completes identity authentication.

Creation time Time when application was created

Description Description of the application

API list List of APIs bound to the application

DetailsaboutpurchasedAPIs

API Calling >PurchasedAPIs > APIgroup name

Group Name Name of the purchased API group

Access DomainName

Domain name used to access the APIgroup

Used API Requests Number of times that APIs in the APIgroup have been used

Remaining APIRequests

Number of remaining times that APIsin the API group can be used

Purchased Time when the API group waspurchased

Expires Time when the API group will expire

Billing Mode Method of charging for calling APIsin the API group

Description Description about the API group,which is provided by the APIprovider

Purchased APIs All APIs in the API group



5 Application Management

Creating an Application

Editing an Application

Deleting an Application

Associating an Application with an API

Resetting AppSecret

Viewing API Details

Disassociating an Application from an API

5.1 Creating an Application

ScenarioFor an API that is called using APP authentication, you need to create an application togenerate an application ID and key pair (AppKey and AppSecret). The API can be calledusing APP authentication only after it is bound with the application. During API calling, thekey pair is replaced by that in the SDK, and API Gateway authenticates the identity of theAPI caller based on the key pair. For details about APP authentication, see the API GatewayDeveloper Guide.

NOTE

l Each API purchased from the marketplace comes with an application, so you do not need to createone again.

l For an API that is called using NONE or IAM authentication, you do not need to create anyapplication.

l You can create a maximum of 50 applications. The application quota includes applications createdby you and those generated after you purchase APIs from the API marketplace.

Procedure



API GatewayUser Guide (API Calling) 5 Application Management






Step 5 Click Create Application. On the Create Application page, set the parameters listed inTable 5-1.



ApplicationName





Step 6 Click OK.

The application and its ID are displayed in the application list on the ApplicationManagement page.

Step 7 Click the application name, and view the AppKey and AppSecret on the application detailspage.

----End

5.2 Editing an Application

Scenario

After creating an application, you can modify its configuration parameters.

Prerequisites

An application has been created.

Procedure







Step 5 Use either of the following ways to access the Edit Application page:l Locate the row that contains the target application and click Edit.l Click the name of the target application. In the upper right corner of the application

details page that is displayed, click Edit.

Step 6 Set the parameters in the following table.



ApplicationName





Step 7 Click OK.

----End

5.3 Deleting an Application

Scenario

You can delete an application that no longer provides services.

NOTE

Applications purchased from the Marketplace cannot be deleted.

Prerequisites


Procedure







Step 5 Use either of the following methods to access the Delete Application page:l Locate the row that contains the target application and click Delete.l Click the name of the target application. In the upper right corner of the application

details page that is displayed, click Delete.

Step 6 Click Yes.

NOTE

l Deleting the application may affect the cloud push system.

l If the application has been authorized, the authorization will be automatically released after theapplication is deleted.

----End

5.4 Associating an Application with an API

ScenarioAfter creating an application, you must bind it to an API before you can call the API by usingAPP authentication.

Prerequisitesl An application has been created.l The API with which the application is to be associated has been published.

Procedure





Step 5 Use either of the following methods to access the Associate with API page:l Locate the row that contains the target application and click Associate with API.l Perform the following operations on the application details page:

a. Click the name of the target application.b. On the Associate Throttling Policy with API page that is displayed, click

Associate with API.

Step 6 Select the environment and click Add.

Step 7 Specify API Group and API Name to filter required APIs.

Step 8 Select the API and click Add. The Associate with API page is displayed.

Step 9 Confirm the API and click Associate.

After the binding is successful, you can view the API to which the application has been boundon the application details page.



NOTE

If the API list contains an API to which the application does not need to be bound, click Remove in therow that contains the API.

----End

5.5 Resetting AppSecret

Scenario

You can reset AppSecret to change its value. After you reset the AppSecret, the originalAppSecret becomes unavailable and the API bound with the application cannot be called. Tocall the API, update the AppSecret.

Prerequisites


Procedure





Step 5 Click the name of the target application.

Step 6 In the upper right corner of the application details page that is displayed, click ResetAppSecret.

Step 7 Click OK.

----End

5.6 Viewing API Details

Scenario

After an application is associated with an API, you can view details about the API.

Prerequisitesl An application has been created.l The application has been associated with an API.

Procedure








Step 6 Click the name of the target API.

Step 7 View details about the API.

----End

5.7 Disassociating an Application from an API

ScenarioYou can unbind an application from an API to which it has been bound.

PrerequisitesThe application has been associated with an API.

Procedure






Step 6 Locate the row that contains the target API and click Disassociate.

Step 7 Click Yes.

----End



6 SDK

ScenarioFor an API that is accessed using APP or IAM (AK/SK) authentication, download an SDKand the SDK documents as required, and call the API by following the instructions in thedocuments.

Procedure




Step 4 Choose API Calling > SDK.

Step 5 Click SDK Documentation and Download SDK of the desired language.

----End

API GatewayUser Guide (API Calling) 6 SDK


7 Viewing Purchased APIs

Scenario

View purchased APIs and service details, and debug APIs to check whether the purchasedservices are running properly.

You can call purchased APIs by using APP authentication.

Prerequisite

You have purchased APIs from the marketplace.

Procedure




Step 4 Choose API Calling > Purchased APIs.

NOTE

Click Buy now to go to the API marketplace where you can purchase APIs you need.

Step 5 Click the name of the target API group.

View the purchased APIs in the API group and details about the group.

Step 6 In the Operation column of the desired API, click Debug.

Step 7 On the left side, set API request parameters listed in Table 7-1. On the right side, view theAPI request and response information after you click Send Request.

Table 7-1 Parameters for debugging an API

Parameter Description

Http Method This parameter can be modified only when Method is set to ANY.

API GatewayUser Guide (API Calling) 7 Viewing Purchased APIs


Parameter Description

SuffixPath You can define a path only after you set Matching Method to Prefixmatch.

Parameter This parameter can be modified only when the value of Path containsbraces ({}).

Headers HTTP headers and values.

Query Query parameters and values.

Body This parameter can be modified only when Method is set to ANY,PATCH, POST, or PUT.

Step 8 After setting the request parameters, click Send Request.

Response information of the API call is displayed on the right side.

Step 9 To verify the API service comprehensively, change the request parameters and values to senddifferent requests.

----End

API GatewayUser Guide (API Calling) 7 Viewing Purchased APIs


8 Response Headers

The following table shows the response headers that API Gateway automatically adds to theresponse returned when an API is called.

X-Apig-Mode: debug indicates that the API Gateway debugging information is added to aresponse header.

ResponseHeader

Description Remarks

X-Request-Id Request ID. The value of this parameter will bereturned for all valid requests.

X-Apig-Latency Duration from the time whenAPI Gateway receives arequest to the time when abackend returns a messageheader.

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug.

X-Apig-Upstream-Latency

Duration from the time whenAPI Gateway sends a requestto a backend to the time whenthe backend returns a messageheader.

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug and the backendtype is not Mock.

X-Apig-RateLimit-api

API request limit information.Example: remain:9,limit:10,time:10 seconds

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug and a limit hasbeen posed on the number of times theAPI can be called.

X-Apig-RateLimit-user

User request limitinformation.Example: remain:9,limit:10,time:10 seconds

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug and a limit hasbeen posed on the number of times theAPI can be called by a user.

API GatewayUser Guide (API Calling) 8 Response Headers


ResponseHeader

Description Remarks

X-Apig-RateLimit-app

App request limit information.Example: remain:9,limit:10,time:10 seconds

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug and a limit hasbeen posed on the number of times theAPI can be called by an App.

X-Apig-RateLimit-api-allenv

Default API request limitinformation.Example: remain:199,limit:200,time:1 second

This parameter will be returned onlywhen the request header contains X-Apig-Mode: debug.

API GatewayUser Guide (API Calling) 8 Response Headers


9 Error Codes

Table 9-1 lists the error codes that may be encountered during an API call.

Table 9-1 Error codes

ErrorCode

Error Message HTTPStatusCode

Description Solution

APIG.0101

The API does not exist orhas not been published inan environment

404 The API does notexist or has notbeen published toan environment.

Check whether thedomain name,method, and path areconsistent with thoseof the registeredAPI. Check whetherthe API has beenpublished. If it hasbeen published in anon-productionenvironment, checkwhether the x-stageheader in the requestis the environmentname.

APIG.0103

The backend cannot befound

404 No backendservices arefound.

Contact technicalsupport.

APIG.0104

Plug-ins cannot be found 400 No pluginconfigurations arefound.


APIG.0105

Backend configurationscannot be found

400 No backendconfigurations arefound.


API GatewayUser Guide (API Calling) 9 Error Codes


ErrorCode



APIG.0106

Arrange error 400 An orchestrationerror occurs.

Check whether thefrontend andbackend parametersof the API arecorrect.

APIG.0201

Bad request 400 The requestparameters areinvalid.

Use valid requestparameters.

APIG.0201

Request entity too large 413 The size of therequest bodyexceeds 12 MB.

Reduce the size ofthe request body.

APIG.0201

Request URI too large 414 The request URIis too large.

Reduce the size ofthe request URI.

APIG.0201

Request headers too large 494 The requestheaders are toolarge.

Reduce the size ofthe request headers.

APIG.0201

Backend unavailable 503 The backendservice isunavailable.

Check whether thebackend service IPaddress configuredfor the API isaccessible.

APIG.0201

Backend timeout 504 The backendservice has timedout.

Increase the timeoutperiod or reduce theprocessing time ofthe backend service.

APIG.0301

Incorrect IAMauthenticationinformation

401 The IAMauthenticationinformation isincorrect.

Check whether thetoken is correct.

APIG.0302

IAM user not allowed toaccess the API

403 An IAM user isnot allowed toaccess the API.

Check whether theuser is restricted bya blacklist orwhitelist.



ErrorCode



APIG.0303

Incorrect applicationauthenticationinformation

401 The APPauthenticationinformation isincorrect.

Check whether therequest method,path, queryparameters, andrequest body areconsistent with thoseused for signature;check whether thedate and time on theclient are correct.

APIG.0304

Application not allowedto access the API

403 The application isnot allowed toaccess the API.

Check whether theapplication has beenauthorized to accessthe API.

APIG.0305

Incorrect authenticationinformation

401 Theauthenticationinformation isincorrect.

Check whether theauthenticationinformation iscorrect.

APIG.0306

Not allowed to access api 403 Access to the APIis not allowed.

Check whetherauthorization hasbeen obtained toaccess the API.

APIG.0307

Access to this API is notallowed

403 The token needsto be updated.

Update the token.

APIG.0308

Throttling thresholdreached

429 The throttlingthreshold hasbeen reached.

Try again after thethrottling policy isrefreshed.

APIG.0401

Unidentified client IPaddress

403 The client IPaddress cannot beidentified.


APIG.0402

IP address not allowed toaccess the API

403 The IP address isnot allowed toaccess the API.

Check whether theIP address isrestricted by ablacklist or whitelist.

APIG.0404

Backend IP address isdenied

403 The backend IPaddress cannot beaccessed.

Check whether thebackend IP addressor the IP addresscorresponding to thebackend domainname is accessible.



ErrorCode



APIG.0501

All application quota hasbeen used

405 Application quotahas been reached.

Increase the quota.

APIG.0502

The application has beenfrozen

405 The applicationhas been frozen.

Check whether youraccount balance issufficient.

APIG.0601

Internal server error 500 An internal erroroccurs.


APIG.0602

Bad request 400 The request isinvalid.

Check whether therequest is valid.

APIG.0605

Domain name resolutionfailed

500 Domain nameresolution fails.

Check whether thebackend address is adomain name thatexists.

APIG.0606

API configurations arenot loaded

500 APIconfigurations arenot loaded.


APIG.0607

Scheme not allowed,allowed scheme is {xxx}

400 The protocol isnot supported.Only xxx isallowed.xxx is subject tothe actual valuein the response.

Use the promptedprotocol (HTTP orHTTPS) to accessthe API.

APIG.0608

The admin account tokencannot be obtained

500 The adminaccountinformationcannot beobtained.


APIG.0609

The VPC backend cannotbe found

500 The VPCbackend servicecannot be found.


APIG.0610

No backend available 502 No backendservices areavailable.

Check whether allbackend services areavailable.

APIG.0611

The backend port cannotbe found

500 The backend portis not found.




ErrorCode



APIG.0612

An API cannot call itself 500 An API cannotcall itself.

Modify the backendconfigurations, andensure that thenumber of layers theAPI is recursivelycalled does notexceed 10.

APIG.0705

Backend signaturecalculation failed

500 Backendsignaturecalculation fails.




10 Auditing

Enabling CTS

If you want to collect, record, or query operation logs of API Gateway in common scenariossuch as security analysis, compliance audit, resource tracing, and problem locating, you needto enable CTS.

With CTS, you can:

l Record audit logs.

l Query audit logs.

l Dump audit logs.

l Encrypt trace files.

l Enable notification of key operations.

Querying Audit Logs

To query audit logs, see Querying Real-Time Traces.

Querying Key Operations

With CTS, you can record operations associated with API Gateway for later query, audit, andbacktrack operations. For details, see Key Operations on API Gateway.

Disabling CTS

To disable CTS, see Deleting a Tracker.

API GatewayUser Guide (API Calling) 10 Auditing


https://support.huaweicloud.com/en-us/qs-cts/en-us_topic_0030598498.html#

https://support.huaweicloud.com/en-us/qs-cts/en-us_topic_0030598499.html

https://support.huaweicloud.com/en-us/usermanual-cts/en-us_topic_0100498011.html#

https://support.huaweicloud.com/en-us/usermanual-cts/en-us_topic_0030628005.html

11 Monitoring

API Gateway Metrics

Creating Alarm Rules

Viewing Metrics

11.1 API Gateway Metrics

Table 11-1 API Gateway metrics

Metric Description

Number ofrequests

Total number of API requests

Average latency Average invocation latency of a single API in a specified period

Maximumlatency

Maximum invocation latency of a single API in a specified period

Upstreamtraffic

Total requested traffic of the API in a specified period

Downstreamtraffic

Total returned traffic of the API in a specified period

5xx error Total number of 5xx errors returned for your API requests

4xx error Total number of 4xx errors returned for your API requests

11.2 Creating Alarm Rules

ScenarioYou can create alarm rules with specified monitored objects and notification policies. Thishelps you track the running status of API Gateway to prevent service abnormalities.

API GatewayUser Guide (API Calling) 11 Monitoring


An alarm rule includes the rule name, monitored object, metric, alarm threshold, monitoringinterval, and whether to send a notification.

Prerequisites

An API has been called.

Procedure




The navigation pane contains four columns: Dashboard, API Publishing, API Calling, andDocumentation.

Step 4 Choose API Publishing > API Management.

Step 5 Click the name of the target API. The Monitoring page is displayed.

Step 6 Click View More Metrics. On the Cloud Eye console that is displayed, create alarm rules byfollowing the procedure in Creating Alarm Rules.

----End

11.3 Viewing Metrics

Scenario

Cloud Eye monitors the running status of API Gateway, and you can view the API Gatewaymetrics on the Cloud Eye console.

Prerequisites

An API group and APIs have been created.

Procedure




The navigation pane contains four columns: Dashboard, API Publishing, API Calling, andDocumentation.

Step 4 Choose API Publishing > API Management.

Step 5 Click the name of the target API. The Monitoring page is displayed.

View API metrics.



https://support.huaweicloud.com/en-us/usermanual-ces/en-us_topic_0084572213.html

Step 6 Click View More Metrics. The Cloud Eye monitoring page is displayed, where you can viewmore monitoring statistics.

NOTE

The monitoring data is retained for two days. To retain the data for a longer time, you need to configureOBS buckets and save the data in these OBS buckets. For details, see Transferring Metric Data toOBS.

----End





12 FAQs

How Is API Gateway Charged?

What Are the Relationships Between an API, Environment, and App?

How Can I Use API Gateway?

Why Does a Backend Service Fail to Be invoked?

What Is an Error Message Returned by API Gateway Like?

Do I Need to Publish an API Again After Modification?

How Can I Protect My APIs?

Can Mobile Applications Call APIs?

Can I Upload Files Using the POST Method?

Can Applications Deployed in a VPC Call APIs?

How Can I Ensure the Security of Backend Services Invoked by API Gateway?

What SDK Languages Does API Gateway Support?

How Can I Make an API Published in a Non-RELEASE Environment Accessible?

Does API Gateway Support Multiple Backend Endpoints?

What Is the Maximum Size of an API Request Package?

12.1 How Is API Gateway Charged?You can enable API Gateway and create and manage APIs for free. You only need to pay forthe number of API calls and the amount of data transmitted. There are no minimum charges orupfront commitments.

API GatewayUser Guide (API Calling) 12 FAQs


12.2 What Are the Relationships Between an API,Environment, and App?

An API can be published in different environments, such as RELEASE (online environment)and BETA (test environment).

An App refers to the identity of an API caller. After you create an App, the systemautomatically generates an AppKey and AppSecret for authenticating the App. After an APIis published and authorized to a specified App, the App owner can call the API.

When publishing an API in different environments, you can define different request throttlingpolicies and authorize different Apps to call the API. For example, during the test process,API v2 can be published in the BETA environment and authorized to the test Apps. API v1 isa stable version and can be authorized to all users or Apps in the RELEASE environment.

12.3 How Can I Use API Gateway?You can use API Gateway to manage and call APIs through the following methods:

l Management console, a web-based service management platformAfter registering with the public cloud platform, log in to the management console, andchoose All Services > Application > API Gateway.

l SDKs of multiple languages such as Java, Go, Python, JavaScript, C#, PHP, C++, and C.You can download the SDKs to call APIs. For details, see the API Gateway DeveloperGuide.

12.4 Why Does a Backend Service Fail to Be invoked?A backend service may fail to be invoked due to the following causes.

Possible Cause Solution

The backend service IP address is incorrect. Change the backend service IP address inthe API definition.

The timeout duration is incorrect.If the backend service fails to return aresponse within the configured timeoutduration, API Gateway displays a messageindicating that the backend service fails tobe invoked.

Increase the backend timeout duration in theAPI definition.

The security group of the Elastic CloudServer (ECS) on which the backend serviceis deployed cannot be accessed.

Ensure that the inbound and outbound portsand protocols of the service are correct.





12.5 What Is an Error Message Returned by API GatewayLike?

When receiving an API request, API Gateway returns a response. A similar response body isas follows:

{ "error_code": "APIG.0101", "error_msg": "API not exist or not published to environment", "request_id": "acbc548ac6f2a0dbdb9e3518a7c0ff84"}l "error_code": indicates an error code.l "error_msg": indicates an error message.

12.6 Do I Need to Publish an API Again AfterModification?

Yes. After an API is published, if you modify its parameters, you must publish the API againto synchronize the modified information to the environment.

12.7 How Can I Protect My APIs?Bind request throttling policies to your APIs to protect the APIs against a large number ofrequests. By default, an API can be called up to 200 times per second.

12.8 Can Mobile Applications Call APIs?Yes, mobile Apps can call APIs. In App authentication mode, the AppKey and AppSecret of amobile App are replaced with those in the relevant SDK to sign the App.

12.9 Can I Upload Files Using the POST Method?Yes, you can upload files using the POST method. The maximum size of an API requestpackage is 12 MB.

12.10 Can Applications Deployed in a VPC Call APIs?Yes, applications deployed in a Virtual Private Cloud (VPC) can call APIs by default. Ifdomain name resolution fails, configure a DNS server on the current endpoint by followingthe instructions in Configuring an Intranet DNS Server. After the configuration,applications deployed in the VPC can call APIs.

Configuring an Intranet DNS Server

To configure a DNS server, specify its IP address in the resolv.conf file under the /etcdirectory.



The IP address of the intranet DNS server depends on which region you are located in. Obtainthe IP address of the intranet DNS server in your region from Table 12-1.

Table 12-1 Mapping between intranet DNS server IP addresses and regions

Region DNS Server IP Address

CN North-Beijng1 100.125.1.250

CN South-Guangzhou 100.125.1.250

CN East-Shanghai2 100.125.17.29

Add an intranet DNS server by using either of the following two methods:

l Method 1: Modify the subnet information of the VPC.l Method 2: Edit the resolv.conf file under the /etc directory.

NOTE

The intranet DNS server configuration becomes invalid every time the ECS restarts, and theintranet DNS server must be configured again. Therefore, method 1 is recommended.

Method 1Perform the following procedure to add a DNS server IP address to the subnet configurationsof the ECS in the VPC. The following procedure is based on CN North-Beijng1.



Step 3 In the service list, choose Computing > Elastic Cloud Server.

Step 4 Click the name of the ECS to be used.

Step 5 On the ECS details page, click the NICs tab, and click to view the subnet name of theECS.

The following figure highlights the subnet name subnet-9c19 of the ECS.



Step 6 On the ECS details page, view the VPC name of the ECS.

The following figure highlights the VPC name vpc-9c19 of the ECS.

Step 7 Click the VPC name to visit the VPC console.

Step 8 On the VPC page, click the VPC name obtained in step Step 6.

Step 9 On the Subnets tab page, find the subnet name obtained in step Step 5, and click Modify inthe Operation column.

Step 10 Modify the DNS information of the subnet, and then click OK to save the modifications.

Change DNS Server Address 1 to 100.125.1.250.



Step 11 Restart the ECS. Check whether the resolv.conf file under the /etc directory contains the IPaddress of the DNS server to be configured, and whether the IP address precedes that of anyother DNS server.

The following figure shows the IP address 100.125.1.250 of the DNS server to be configured.

NOTE

Modifying the subnet information of a VPC will affect all ECSs created using the subnet.

----End

Method 2Add the IP address of the intranet DNS server to the resolv.conf file under the /etc directory.

For example, if you are located in North China-Beijing 1, add the intranet DNS server of IPaddress 100.125.1.250 to the resolv.conf file.

NOTE

l The IP address of the new DNS server must precede that of any other DNS server.

l The DNS configuration takes effect immediately after the resolv.conf file is saved.



12.11 How Can I Ensure the Security of Backend ServicesInvoked by API Gateway?

You can ensure the security of backend services invoked by API Gateway by using thefollowing methods:

l Bind a signature key to an API. After a signature key is bound to the API, API Gatewayadds signature information to the request sent to the backend service. After receiving therequest, the backend service calculates the signature information and checks whether it isconsistent with that on API Gateway.

l Encrypt requests using HTTPS. Before using this method, ensure that the required SSLcertificates are available.

12.12 What SDK Languages Does API Gateway Support?API Gateway supports SDKs of multiple languages such as Java, Go, Python, C#, JavaScript,PHP, C++, and C.

12.13 How Can I Make an API Published in a Non-RELEASE Environment Accessible?

To make an API published in a non-RELEASE environment accessible, add the x-stageheader to the API request. For details, see Step 5 in API Calling.

12.14 Does API Gateway Support Multiple BackendEndpoints?

Yes, API Gateway supports multiple backend endpoints by using VPC channels. You can addmultiple ECSs to a VPC channel.

12.15 What Is the Maximum Size of an API RequestPackage?

The maximum size of an API request body is 12 MB.




A What's New

Table A-1 Change history

Date Description

2018-08-31 Added steps of debugging an API in section "Purchased APIs".

2018-07-16 Added chapter "Experiencing the Demo" to demonstrate how touse API gateway with a few clicks.

2018-05-30 Added chapter "Error Codes".

2018-05-02 l Added chapter "API Gateway and Other Services".l Added chapter "Monitoring".l Added chapter "Auditing".

2018-04-04 Adjusted the quota of the applications.

2018-03-09 Added section "Enabling CTS".

2018-01-31 Added chapter "SDK".

2017-12-25 This issue is the first official release.

API GatewayUser Guide (API Calling) A What's New


user guide (api calling) - developer-res-cbc-cn.obs.cn ...€¦ · api gateway user guide (api...

Documents