edit-icon download-icon

Create an API

Last Updated: Jun 14, 2018

When you create an API, you must enter the basic information about the API, and define the API request information, the API backend service, and response information. Then, debug the API and set the security configuration. After testing the API, if it works properly, you can publish it to the Release environment for your users.

Define an API

On the API List page in the API Gateway console, click Create API to enter the API creation and definition process.

Basic Information of API

Basic API information includes the API group, API name, security certification method, visibility type, and description.

  • Group: APIs are managed by group. Before creating an API, you must first create a group (for more information about API groups, see Open an API).

  • API Name: It is the name of an API and also an unique identifier within its group.

  • Security Certification: This method is used to authenticate API requests. Currently, the three methods available are Alibaba Cloud App, OpenID Connect, and No Certification.

    • Alibaba Cloud App: When the requestor calls this API, they must pass the identity authentication of this app.

    • OpenID Connect: This is a lightweight standard based on OAuth 2.0, which provides a framework for identity interaction through RESTful APIs. You can use OpenID Connect to connect seamlessly to your own account system. For a detailed introduction, see OpenID Connect.

    • No Certification: Any person who knows this API’s request definitions can initiate a request. The gateway does not verify their identities, but directly forwards the requests to your backend service. (We strongly recommend not to use this method.)

  • Visibility: Public or Private.

    • Public APIs: All the users can view a certain sections of the API’s information on the Published API page of the API Gateway console.

    • Private APIs: You must manually grant authorization to the user, if the user wants to call your private API.

  • Description: A description of the functions of an API.

Define API request

This part defines how users can send requests to your API, including the relevant protocols, request paths, HTTP methods, request modes, and input parameter definitions.

  • Protocol: Supports HTTP and HTTPS.

  • Request Path: The path refers to the API request path for the corresponding service host. The request path can be different from the actual backend service path. You can write any valid and semantically-clear path for users. You can configure dynamic parameters in the request path that require users to input parameters in the Path field. At the same time, the backend service receives parameter from the Path, which are mapped to Query, Header and other locations. In Published API to API Gateway, you can find detailed examples and operation screenshots.

  • HTTP Method: Supports standard HTTP methods. You can select PUT, GET, POST, DELETE, PATCH, or HEAD.

  • Request Mode: API Gateway used this mode to process input parameters, Request Parameter Mapping or Request Parameter Passthrough.

    • Request Parameter Mapping: When API Gateway receives a request for your API, it uses mapping relationships to convert the request to the format required by your backend service.

      Request Parameter Mapping mode features:

      • Definition method: When defining this API, you must add the frontend and backend parameter mapping relationships.

      • Scenarios:

        • For the same interface, define different APIs in API Gateway to provide differentiated services to users.

        • Use API Gateway to standardize legacy system interfaces.

      • Functions:

        • You can configure full frontend to backend mapping, that is, parameter shuffling. For example, you can require API users enter parameters in the Query field and set the backend to receive the information in the Header field.

          Supports parameter name conversion and parameter location conversion.

        • You can define parameter verification rules to pre-verify the request parameters, and to reduce the volume of invalid parameters that are processed in the backend.

          Supports length verification, parameter value verification, parameter regular expression verification, and parameter JSON schema verification.

    • Request Parameter Passthrough: After API Gateway receives an API request, it does not process the request, but directly forwards it to the backend service. In this mode:

      • You cannot implement parameter verification.

      • You cannot generate detailed API calling documentation.

      • Automatically-generated SDKs do not include request input parameters.

  • Input Parameter Definition: You can define API request input parameters in this section, including parameter names, parameter locations, types, required or not, their default values, examples, and descriptions. In Request Parameter Passthrough mode, users do not have to enter parameters.

    • Parameter Name: The parameter name displayed to users.

    • Parameter Location: The location of the parameter mentioned in the request that includes Head, Query, and Parameter Path.

      Note: If you configure dynamic parameters in Path, the parameter location also defined as Parameter Path.

    • Type: The field type; optional values: String, Int, Long, Float, Double, and Boolean.

    • Required: Indicates whether this parameter is required. When set to Yes, API Gateway verifies that user requests contain this parameter. Requests without this parameter are rejected.

    • Default Value: This option is applied when Required is set to No. If a user’s request does not contain the corresponding parameter, API Gateway automatically adds the default value before sending the request to the backend service.

    • Example: An example of defining parameters.

    • Description:Provides a brief description about the parameter and also mentions points to consider while using it.

    • Parameter Verification Rules: Click More to configure verification rules for the parameter value, including string length, the minimum and maximum values, enumeration, regular expressions, JSON schema, and other attributes. API Gateway uses the verification rules to perform preliminary inspections on requests. If an input parameter is invalid, the request is not sent to the backend service. This is to reduce the backend processing load.

Define API backend service

This part mainly defines parameter mapping between the frontend and backend. This is the API backend service configuration, including the backend service address, backend path, backend time-out, parameter mapping, constant parameters, and system parameters. After user requests reach API Gateway, it maps the received requests according to your backend configuration, to the format required by the backend service before the requests are forwarded to the backend service.

  • Backend Service Type: Currently supports HTTP/HTTPS and Function Compute.

    • HTTP/HTTPS: Select this option if your service is an HTTP/HTTPS service.

      NOTE: If you have an HTTPS service, the backend service must have an SSL certificate.

    • Function Compute: If you select Function Compute for the backend service, you must first create a function in the Function Compute console, enter the function’s service name and function name, and obtain Function Compute’s role Arn.

  • Backend VPC Access: When your backend service is in a VPC network, you must select Enable. For the usage method, see Open an API in a VPC environment.

  • Backend Service Address: The host of the backend service. This can be a domain name and in an ‘http(s)://host:port’ format. This value must begin with “http://“ or “https://“.

  • Backend Request Path: This path is the actual request path of your API service on the backend server. If your backend path receives dynamic parameters, specify a particular location and name of the parameter a caller must enter. This declares the corresponding mapping relationship.

  • Backend Timeout: This is the maximum length of time during which an API must receive a response from the backend service of the called API. This period starts when API Gateway sends a request to the backend service and ends when API Gateway receives a response result from the backend service. Units: milliseconds. This value cannot exceed 30 seconds. If the response time exceeds this value, API Gateway abandons the request and returns the corresponding error message to the user.

  • Constant Parameters: You can configure constant parameters. These parameters are invisible to the users. However, when requests pass through API Gateway, it adds these parameters to the specified locations in the requests before forwarding the requests to the backend service. This is used to address certain business needs of the backend service. For example, if you require that each request sent by API Gateway to the backend service carry the keyword aligateway, you can configure aligateway as a constant parameter and specify the location where it is received.

  • System Parameters: These are API Gateway system parameters. By default, system parameters are not transmitted to you. However, to obtain system parameters, configure their locations and names in the API. The specific content is shown in the following table.

    Parameter Description
    CaClientIp IP address of the client sending the request
    CaDomain Domain name sending the request
    CaRequestHandleTime Request time (GMT)
    CaAppId The ID of the request app
    CaRequestId RequestId
    CaApiName API name
    CaHttpSchema Protocol used by the user to call the API: HTTP or HTTPS.
    CaProxy Proxy (AliCloudApiGateway)

    Note: You must make sure that the names of all parameters are globally unique, including the dynamic parameters in Path, Headers parameters, Query parameters, Body parameters (non-binary), constant parameters, and system parameters. If you have a parameter called name in the Headers and Query fields at the same time, the system reports an error.

Part 4: Define response

Enter the returned ContentType, response example, failed response example, and error code definitions.

Debug an API

After you define an API successfully, you can debug it on the API debugging page to verify its correctness and usability.

After you create and define an API, you can test whether the created API is usable and the request chain is correct.

  1. Click the API name or the Manage button to go to the API Definition page.

  2. Click Debug API from the left-side navigation pane.

  3. Enter the request parameters and click Send Request.

    The returned results are displayed on the right side of the page.

    If it returns a successful result, it indicates that the API can be used.

    If a 4XX or 5XX error code is returned, it indicates that the request has encountered an error. For more information, see How to obtain the error message and Error code table.

Subsequent steps

After completing the API definition and preliminary debugging, you have finished creating an API. You can publish the API in the Test, Pre, or Release environments for ongoing debugging or for the other users to use. You can also bind a Signature key to the API and set Throttling and other security configurations.

Thank you! We've received your feedback.