This topic describes how to create and debug an API and perform security configurations for the API. To create an API, you must configure basic information, request information, a backend service, and response information for the API. After you debug the API, you can publish the API for users to call.
1 Create an API
Log on to the API Gateway console. In the left-side navigation pane, choose Publish APIs > APIs. On the API List page, click Create API. Then, you can create and configure an API.
1.1 Configure basic information
Parameter | Description |
|---|---|
Group | The basic management unit of APIs. Before you create an API, you must create an API group. When you select an API group, the region where the API group is created is selected for the API. |
API Name | The name of the API that you want to create. Each API name in an API group must be unique. |
Security Certification | The authentication mode of API requests. Valid values: Alibaba Cloud APP, OpenID Connect, OpenID Connect & Alibaba Cloud APP, and No Certification.
|
Signature Method | The algorithm that is used to sign API requests. Valid values:
|
Description | The description of the API. |
1.2 Define an API request
Define an API request. The detailed configurations include Protocol, Request Path, HTTP Method, Request Mode, and Input Parameter Definition.
Parameter | Description |
|---|---|
Request Type | The request type. Valid values: COMMON: indicates common HTTP or HTTPS requests. REGISTER (WEBSOCKET): indicates the bidirectional control signaling used to register devices. It is sent from the client to the server. UNREGISTER (WEBSOCKET): indicates the bidirectional control signaling used to deregister devices. It is sent from the client to the server. After a device is deregistered, it no longer receives server-to-client notifications. NOTIFY (WEBSOCKET): After receiving the registration signaling sent from the client, the backend service records the device ID and sends a server-to-client notification to API Gateway. Then, API Gateway sends the notification to the device. If the client is connected, API Gateway can send the server-to-client notification to the client. |
Protocol | The network protocol that is used to initiate the request. Valid values: HTTP, HTTPS, and WEBSOCKET. |
Request Path | The API request path that corresponds to the service host. The request path can be different from the actual backend service path. You can specify a valid path with correct semantics as the request path. You can configure dynamic parameters in the request path. This requires users to specify path parameters in the request. At the same time, the path parameters can be mapped to the query and header parameters that are received by the backend service. |
HTTP Method | The standard HTTP request method. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY. |
Request Mode | Valid values: Request Parameter Mapping (Filter Unknown Parameters), Request Parameter Mapping (Passthrough Unknown Parameters), and Request Parameter Passthrough.
|
Input Parameter Definition: The request parameters of your API. You can specify different request parameters for different parameter paths. You can select Head, Query, Body, or Parameter Path from the Param Location drop-down list. When you configure a dynamic path parameter, you must provide a description of this dynamic parameter in the Input Parameter Definition section. The following data types are supported: String, Int, and Boolean.
Note that the names of all parameters must be unique.
You can use the upwards and downwards arrows in the Order column to adjust the parameter order.
To delete a parameter that is no longer required, you can click Remove in the Operation column.
If you have configured a dynamic parameter in the request path, you must define a parameter with the same name as the dynamic parameter and set Param Location to Parameter Path.
Configure parameters verification rules: Find the parameter for which you want to configure verification rules and click More in the Operation column. For example, you can specify Max Length and Enumeration. API Gateway pre-verifies requests based on the verification rules. Requests with invalid parameters are not sent to your backend service. This reduces the workload on your backend service.
1.3 Define an API backend service
Define mappings between the request and response parameters and configure the information of the backend service of your API. The information includes Backend Service Address, Backend Request Path, Backend Timeout, and Backend Service Parameter Configuration, Constant Parameter, and System Parameter. After receiving a request, API Gateway converts the format of the request into the format that is required by your backend service based on the backend service configuration. Then, API Gateway forwards the request to your backend service.
Define a backend service
Parameter | Description |
|---|---|
Backend Service Type | Valid values: HTTP(s) Service, Function Compute, VPC, and Mock.
|
VPC Access Name | If your backend service is deployed in a VPC, you must specify a VPC access name. |
Backend Service Address | The host name of the backend service. It can be a domain name or a value in the format of http(s)://host:port. The address must start with http:// or https://. |
Backend Request Path | The actual request path of your API on your backend server. If you want to receive dynamic parameters in the backend path, you must declare parameter mappings by specifying the locations and names of the corresponding request parameters. |
HTTP Method | The standard HTTP request method. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY. |
Backend Timeout | The response time for API Gateway to access the backend service after API Gateway receives an API request. The response time is from the time when API Gateway sends an API request to the backend service to the time when API Gateway receives a response returned by the backend service. The response time cannot exceed 30 seconds. If API Gateway does not receive a response from the backend service within 30 seconds, API Gateway stops accessing the backend service and returns an error message. |
Backend Service Parameter Configuration: API Gateway can set up mappings between the request and response parameters, including a name mapping and a location mapping. API Gateway can map a path, header, query, or body request parameter to a response parameter at a different location. This way, you can package your backend service into a standardized and professional API form. This part declares the mappings between the request and response parameters.
Constant Parameter: You can configure constant parameters for API requests. The constant parameters include Backend Param Name, Param Value, Param Location, Description, and Operation. Constant parameters are invisible to your users. After API Gateway receives requests, API Gateway adds these parameters to the specified locations in each request and forwards the requests to your backend service. If you want API Gateway to attach the abc parameter to each request that API Gateway forwards to your backend service, you can configure this parameter as a constant parameter. After API Gateway receives a request, API Gateway automatically adds the parameter to the specified location and forwards the request to your backend service.
System Parameter: the system parameters that apply globally in API Gateway. By default, API Gateway does not add system parameters to API requests. If you want to obtain the system parameters, you can configure their locations and names. The following table describes the system parameters.
Parameter | Description |
|---|---|
CaClientIp | The IP address of the client that sends an API request. If you have configured Web Application Firewall (WAF) or Content Delivery Network (CDN), the system records their origin IP address. You must check the IP address of the client in X-Forwarded-For. |
CaDomain | The domain name that is used to send an API request. |
CaRequestHandleTime | The request time. It must be in GMT. |
CaAppId | The ID of the application from which an API request is sent. |
CaRequestId | RequestId |
CaApiName | The name of the API. |
CaHttpSchema | The protocol that is used to call the API. Valid values: HTTP and HTTPS. |
CaProxy | The proxy that is used to handle an API request. The value must be set to AliCloudApiGateway. |
CaClientUa | The user agent of the client that sends an API request. |
CaCloudMarketInstanceld | The ID of the instance of the service that is requested. |
CaAppKey | The key of the application from which an API request is sent. |
CaStage | The environment in which you call the API. Valid values: RELEASE, TEST, and PRE. |
You can configure Passthrough HOST Head (Head Domain) for a shared instance on the Group Details page of an API group. If you want to perform the same configuration for a dedicated instance, submit a ticket. After you enable Passthrough HOST Head (Head Domain), API Gateway transparently passes the domain name of an API request to your backend service. Otherwise, API Gateway passes the host name that you specified in API Gateway to your backend service.
For example, if you attach a host name xuemeng.XXXX.com to an API group, the host name of the backend service of APIs in the API group is apigatewayXXXXXXalicloudapi.com:8080. The following figures show different host names received by your backend service before and after Passthrough HOST Head (Head Domain) is enabled.
Passthrough HOST Head (Head Domain) is enabled:
Passthrough HOST Head (Head Domain) is disabled:
When you configure parameters for the backend service of the API, make sure that the name of each parameter is globally unique in API Gateway. This applies to dynamic parameters in request paths, header parameters, query parameters, body parameters, constant parameters, and system parameters. Note that values of body parameters must be non-binary. For example, if you specify a header parameter and a query parameter with the same name, an error will occur after you send a request.
1.4 Define response information
Configure Content Type of Response, Sample of Returned Results, Sample of Returned Failure, and Error Code Definition.
2 Debug the API
After you create and configure the API, you can debug the API on the API debugging page. This ensures the usability of the API.
After the API is created and configured, you are navigated to the API List page. To debug the API, perform the following steps:
Find the API that you created and click its name or click Manage in the Operation column to go to the API Definition page.
In the left-side navigation pane of the API Definition page, click Debug API.
On the page that appears, specify request parameters in the Request Parameters section and click Send Request.
A result appears on the right side of the page.
If a success response is returned, the API can be called.
If an HTTP status code 4XX or 5XX is returned, an error occurred during the API call. For more information, see How to obtain the error message and Error code table.
3 What to do next
After you configure and debug the API, the creation of the API is complete. You can publish the API to the test, staging, or production environment for further debugging or for users to call. You can also perform security configurations for the API. For example, you can attach the Request signature documentation for the API.