This topic describes how to create and debug an API operation and also touches upon security configurations for API operations. To create an API operation, you must configure basic information, request information, a backend service, and response information for the API operation. After you debug the API operation, you can publish the API operation for users to call.

Create and configure an API operation

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.

Step 1: Configure basic information for the API operation

In this step, configure basic information for the API operation to be created, including the following parameters:

  • Group: the API group to which the API operation belongs. In API Gateway, API operations are managed in API groups. Before you create an API operation, you must create an API group. For more information about API Groups, see Enable API services.
  • API Name: the name of the API operation. The name must be unique within the API group to which the API operation belongs.
  • Security Certification: the authentication method to be used to call the API operation. Valid values:

    • Alibaba Cloud APP: The application from which each API request is sent must be checked whether it is authorized to call the API operation.
    • OpenID Connect: OpenID Connect is a simple authentication layer on top of OAuth 2.0, an authorization framework that implements identity interaction and authorization by using RESTful API operations. If you select this method, the OpenID Connect authentication layer will be integrated with API Gateway and the backend service of the current API operation to implement authentication. For more information, see Implement OpenID Connect authentication by using API Gateway.
    • OpenID Connect & Alibaba Cloud APP: Both the OpenID Connect authentication layer and Alibaba Cloud APP authentication method are used for identity authentication during API calls.
    • No Certification: This method allows all users who know the request definition of the API operation to send API requests. API Gateway directly forwards each API request to the backend service without identity authentication. We recommend that you do not set Security Certification to No Certification.
  • Description: the description of the API operation.

Step 2: Configure request information for the API operation

In this step, define how a user sends an API request for the API operation, including the following parameters:

  • Protocol: the protocol that can be used by each request for the API operation. Valid values: HTTP, HTTPS, and WEBSOCKET.
  • Request Path: the custom request path of the API operation. The request path can be different from the actual path of the backend service. You can set a valid and informative path as the request path. You can configure one or more dynamic parameters in the request path. This requires API callers to specify the dynamic parameters in the request path for each API request. Each dynamic parameter in the request path can be mapped to a request parameter in a specific location, such as a query parameter or a header parameter, before API Gateway routes the API request to the backend. For more information, see Publish an API operation.
  • HTTP Method: the HTTP method that can be used to send requests for the API operation. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY.
  • Request Mode: the mode in which API Gateway handles request parameters in API requests. Valid values: Request Parameter Mapping(Filter Unknown Parameters), Request Parameter Mapping(Passthrough Unknown Parameters), and Request Parameter Passthrough.
    • Request Parameter Mapping(Filter Unknown Parameters) and Request Parameter Mapping(Passthrough Unknown Parameters): API Gateway performs parameter mapping to convert each API request to the specified format that can be received by the backend service of the API operation. Take note of the following items when you set Request Mode to Request Parameter Mapping(Filter Unknown Parameters) or Request Parameter Mapping(Passthrough Unknown Parameters):
      • Requirement: You must further define parameter mapping rules to map request parameters that are defined for the API operation to request parameters in the format that can be received by the backend service of the API operation.
      • Scenarios:
        • Create different API operations for the same backend service to serve different users.
        • Create API operations in API Gateway to standardize outdated system interfaces.
      • Features:
        • API Gateway supports global parameter mapping, namely, API Gateway can map a parameter in a location to a parameter in a different location. For example, API Gateway can map a request parameter in the Query location to a parameter in the Header location before API Gateway routes the request to the backend. Both the name and location of a parameter can be mapped.
        • You can define verification rules to verify request parameters in each API request. This filters out invalid requests and reduces the workload of the backend. You can define rules to verify the length, numeric value, or JSON schema of a request parameter. You can also define regular expressions for request parameters of the STRING type.
    • Request Parameter Passthrough: API Gateway does not handle request parameters and directly forwards each API request to the backend service of the API operation. Take note of the following items when you set Request Mode to Request Parameter Passthrough:
      • Parameter verification is not supported.
      • API Gateway will not generate a detailed description of how to call the current API operation in the SDK that is generated for the API group to which the API operation belongs.
      • The SDK that API Gateway automatically generates for the API group, to which the current API operation belongs, will not contain the request parameters of this API operation.
  • Input Parameter Definition: the request parameters of the API operation. For each request parameter, configure the following information. Note that if you set Request Mode to Request Parameter Passthrough, you do not need to define request parameters.
    • Param Name: the name of the parameter.
    • Param Location: the location of the parameter in each API request. Valid values: Head, Query, and Parameter Path.
      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.
    • Type: the data type of the parameter. Valid values: String, Int, Long, Float, Double, Boolean, and Array.
    • Required: specifies whether the parameter is required. If you select the check box, API Gateway will check whether this parameter is specified in each request for the API operation. If this parameter is not specified in the request, API Gateway will reject the request.
    • Default Value: the default value of the parameter. The specified default value takes effect only for optional request parameters. If an optional request parameter is not specified in a request, API Gateway sets the parameter to the default value in the request before API Gateway routes the request to the backend.
    • Example: a sample value of the parameter.
    • Description: the description of the parameter and how to use the parameter.
    • Parameter verification: Click More in the Operation column and set verification rules in the More dialog box. You can specify a maximum value length, a value range, valid values, regular expressions, or a JSON schema to verify a parameter. API Gateway will verify each request for the API operation based on the verification rules. If a request parameter in an API request is invalid, API Gateway will not route the request to the backend. This reduces the workload of the backend.

Step 3: Configure backend service information for the API operation

In this step, configure a backend service for the API operation. Specifically, you need to specify a backend service address, a backend request path, a backend timeout period, constant parameters, system parameters, and, if required, parameter mapping rules. Assume that parameter mapping rules are configured for the current API operation. After API Gateway receives a request for the API operation, API Gateway maps the request parameters based on the mapping rules before it routes the request to the backend.

  • Backend Service Type: the type of the backend service of the API operation. Valid values: HTTP(s) Service, FunctionCompute, VPC, and Mock.
    • HTTP(s) Service: If you need to configure an HTTP or HTTPS service as the backend service of the API operation, set Backend Service Type to HTTP(s) Service.
      Note To configure an HTTPS service as the backend service, you must first obtain a Secure Sockets Layer (SSL) certificate.
    • FunctionCompute: If you need to use Function Compute as the backend service of the API operation, you must first create a function in the Function Compute console. Then, specify the Service Name, Function Name, and Role Arn parameters in the API Gateway console.
  • Backend Service Address: the host address of the backend service. The address can be a domain name or in the http(s)://host:port format. The address must start with http:// or https://.
  • Backend Request Path: the actual request path of the API operation on the backend server. If you specify a dynamic parameter in the backend request path, you must further define a mapping rule that maps the dynamic parameter to a request parameter in a specific location in each API request.
  • Backend Timeout: the timeout period within which the backend service must return a response after it receives an API request from API Gateway. Unit: milliseconds. The maximum timeout period is 30 seconds. If API Gateway does not receive a response from the backend service within the specified timeout period, API Gateway returns an error message to the client.
  • Constant Parameter: the one or more constant request parameters that do not need to be specified by users in each API request but you want each API request to include. Users may not know these constant parameters. API Gateway adds these parameters to specified locations in each request before it routes the request to the backend. This meets specific requirements of the backend service. For example, you may need each request for the API operation to include a keyword aligateway. In this case, you can define a constant parameter named aligateway and specify a location where this constant parameter is added in each request.
  • System Parameter: the one or more system parameters that apply globally in API Gateway. By default, API Gateway does not add system parameters to API requests. If you need to obtain the value of a system parameter for each request for an API operation, define the system parameter as a request parameter for the API operation. You can set a new name and a location for the system parameter. The following table describes the system parameters.

    Parameter Description
    CaClientIp The IP address of the client from which an API request is sent.
    CaDomain The domain name that is used to send an API request.
    CaRequestHandleTime The time point in UTC at which an API request is received by API Gateway.
    CaAppId The ID of the application from which an API request is sent.
    CaRequestId The ID of an API request.
    CaApiName The name of the API operation that is called by an API request.
    CaHttpSchema The protocol that is used by an API request to call the API operation. Valid values: http and https.
    CaProxy The proxy to handle an API request. The value is fixed to AliCloudApiGateway.
    Note When you configure an API operation, 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.

Step 4: Configure response information for the API operation

In this step, specify a response format, a sample success response, and a sample error response for the API operation. You can also define error codes.

Debug the API operation

After you create and configure the API operation, you can go to the API debugging page to debug the API operation. This helps ensure that the API operation can be called.

After the configurations of the API operation are completed, you are navigated to the API List page. To debug the API operation, perform the following steps:

  1. Find the API operation you created and click its name or click Manage in the Operation column. The API Definition page appears.
  2. In the left-side navigation pane, 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 of the page.

If the result is a success response, the API operation can be called.

If the result includes an error code that starts with the digit 4 or 5, an error occurred in the process of calling the API operation. For more information, see How to obtain the error message and Error code table.

What to do next

After you create and debug the API operation, you can publish the API operation to the test, staging, or production environment for further debugging or for users to call. You can also complete security configurations for the API operation, such as binding the API operation to a Backend Signature and configuring a Throttling policy.