View
29
Download
0
Category
Preview:
Citation preview
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: support@huawei.com
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. i
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 2
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 3
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 4
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 5
– 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.
API GatewayUser Guide (API Calling) 4 Getting Started
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 6
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 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.
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.
API GatewayUser Guide (API Calling) 4 Getting Started
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 7
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
API GatewayUser Guide (API Calling) 4 Getting Started
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 8
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
API GatewayUser Guide (API Calling) 4 Getting Started
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 9
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
Step 1 Log in to the management console.
Step 2 Click in the upper left corner to select a region.
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 10
Step 3 In the service list, choose Application > API Gateway.
Step 4 Choose API Calling > Application Management.
Step 5 Click Create Application. On the Create Application page, set the parameters listed inTable 5-1.
Table 5-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
5.2 Editing an Application
Scenario
After creating an application, you can modify its configuration parameters.
Prerequisites
An application has been created.
Procedure
Step 1 Log in to the management console.
Step 2 Click in the upper left corner to select a region.
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 11
Step 3 In the service list, choose Application > API Gateway.
Step 4 Choose API Calling > Application Management.
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.
Table 5-2 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 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
An application has been created.
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.
Step 4 Choose API Calling > Application Management.
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 12
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 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.
Step 4 Choose API Calling > Application Management.
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.
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 13
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
An application has been created.
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.
Step 4 Choose API Calling > Application Management.
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 1 Log in to the management console.
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 14
Step 2 Click in the upper left corner to select a region.
Step 3 In the service list, choose Application > API Gateway.
Step 4 Choose API Calling > Application Management.
Step 5 Click the name of the target application.
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 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.
Step 4 Choose API Calling > Application Management.
Step 5 Click the name of the target application.
Step 6 Locate the row that contains the target API and click Disassociate.
Step 7 Click Yes.
----End
API GatewayUser Guide (API Calling) 5 Application Management
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 15
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 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.
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 16
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 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.
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 17
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 18
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 19
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 20
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.
Contact technicalsupport.
APIG.0105
Backend configurationscannot be found
400 No backendconfigurations arefound.
Contact technicalsupport.
API GatewayUser Guide (API Calling) 9 Error Codes
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 21
ErrorCode
Error Message HTTPStatusCode
Description Solution
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.
API GatewayUser Guide (API Calling) 9 Error Codes
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 22
ErrorCode
Error Message HTTPStatusCode
Description Solution
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.
Contact technicalsupport.
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.
API GatewayUser Guide (API Calling) 9 Error Codes
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 23
ErrorCode
Error Message HTTPStatusCode
Description Solution
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.
Contact technicalsupport.
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.
Contact technicalsupport.
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.
Contact technicalsupport.
APIG.0609
The VPC backend cannotbe found
500 The VPCbackend servicecannot be found.
Contact technicalsupport.
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.
Contact technicalsupport.
API GatewayUser Guide (API Calling) 9 Error Codes
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 24
ErrorCode
Error Message HTTPStatusCode
Description Solution
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.
Contact technicalsupport.
API GatewayUser Guide (API Calling) 9 Error Codes
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 25
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 26
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 27
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
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, 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
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, 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.
API GatewayUser Guide (API Calling) 11 Monitoring
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 28
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
API GatewayUser Guide (API Calling) 11 Monitoring
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 29
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 30
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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 31
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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 32
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 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 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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 33
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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 34
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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 35
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.
API GatewayUser Guide (API Calling) 12 FAQs
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 36
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
Issue 07 (2018-08-31) Copyright © Huawei Technologies Co., Ltd. 37
Recommended