All Products
Search
Document Center

Create an API

Last Updated: Dec 02, 2020

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.

  • Alibaba Cloud APP: This mode requires the requester to pass the application authentication to call an API.

  • OpenID Connect: OpenID Connect is a simple authentication layer on top of OAuth 2.0. It is an authorization framework that implements identity interaction and authorization by using RESTful APIs. If you select this mode, the OpenID Connect authentication layer is integrated with API Gateway and the backend service of the current API to implement authentication. For more information, see Implement OpenID Connect authentication by using API Gateway.

  • OpenID Connect & Alibaba Cloud APP: Both OpenID Connect and Alibaba Cloud APP are used for user identity authentication during API calls.

  • No Certification: This mode allows all users who understand the request definition of the API to initiate a request. API Gateway directly forwards the request to the backend service without verifying the identity of the requester. We recommend that you do not set Security Certification to No Certification.

Signature Method

The algorithm that is used to sign API requests. Valid values:

  • HmacSHA256

  • HmacSHA1 and HmacSHA256: If you set the parameter to this value, both the algorithms are supported.

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.

  • Request Parameter Mapping (Filter Unknown Parameters): indicates that you must configure request and response data mappings for query, path, and body form parameters. API Gateway transparently passes only the configured parameters to the backend service. Other parameters are filtered out.

  • Request Parameter Mapping (Passthrough Unknown Parameters): indicates that you must configure request and response data mappings for query, path, and body form parameters. API Gateway maps and verifies only the configured parameters and transparently passes unknown parameters to the backend service.

  • Request Parameter Passthrough: indicates that you do not need to configure query and body form parameters. However, you still need to configure path parameters. API Gateway transparently passes all parameters sent from the client to the backend service.

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.

Note

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.

  • HTTP(s) Service: This option is selected by default. It indicates that API Gateway accesses the backend service over HTTP or HTTPS. If API Gateway can directly communicate with the backend service, select this option. To configure an HTTPS service as the backend service, you must first obtain a Secure Sockets Layer (SSL) certificate.

  • Function Compute: If you use Function Compute as the backend service, you must create a function in the Function Compute console and obtain Function Compute Role Arn on the Functions tab. Then, specify Service Name and Function Name.

  • VPC: If the backend service is deployed in a VPC, select this option.

  • Mock: If you want to simulate expected return results, select this option.

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:

Enable Passthrough HOST Head (Head Domain)

Passthrough HOST Head (Head Domain) is disabled:

Disable Passthrough HOST Head (Head Domain)

Note

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:

  1. Find the API that you created and click its name or click Manage in the Operation column to go to the API Definition page.

  2. In the left-side navigation pane of the API Definition page, click Debug API.

  3. 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.