Creating an API_ROMA Connect

Prerequisites

Each API must belong to an integration application. Before creating an API, ensure that an integration application is available, or create one.
Each API must belong to an API group. Before creating an API, ensure that the API group is available, or create one.
If you need to use a load balance channel to access the server where the backend service is located, create a channel first.
If you need to use custom authentication, create a frontend custom authorizer first.
Ensure that the ROMA Connect instance can communicate with your backend service network.
- Same VPC: Let the instance can directly access the backend service.
- Two VPCs in the same region: Connect the instance and the backend service with a peering connection. For details, see VPC Peering Connection.
- Two VPCs in two regions: Create a cloud connection and load the VPCs that need to communicate with each other. For details, see Network Communications Among VPCs Across Regions.
- Communication over the public network: Ensure that the ROMA Connect instance has been bound with an EIP.
To enable cross-VPC private access, configure the routes between the instance and the backend service subnet.
To use FunctionGraph as an API backend service, the user must be assigned the FunctionGraph Administrator role.
In the same instance, the group, request method, request path, and matching mode of two APIs cannot be all the same.

Defining the API Request

Log in to the ROMA Connect console. On the Instances page, click View Console of an instance.
In the navigation pane on the left, choose API Connect > APIs. In the upper right corner, click Create API.

On the page displayed, configure the frontend definition of the API.

**Table 1** Defining the API frontend
Parameter	Description
API Name	Enter an API name. Using naming rules facilitates future search.
Integration Application	Select an integration application for the API. If none is available, click Create Integration Application on the right to create one.
API Group	Select an API group for the API. You can select only the group under the specified integration application or under an All group. If none is available, click Create API Group on the right to create one. NOTE: The API group cannot be changed once set and is bound to the access domain name of the API.
URL	Configure the API access address. Method: Select the API request method. ANY: The API is accessible by any request method. Protocol: Select the request protocol the API will use. HTTPS is recommended for transmitting important or sensitive data. Options: HTTP, HTTPS, HTTP&HTTPS Path: Enter the request path of the API. Example: /getUserInfo/{userId}. The URL can have multiple path parameters, each enclosed by braces. Each path parameter must occupy the entire segment between slashes (/). Wrong example: /abc{userId} If Matching is set to Exact match, a plus sign (+) can be added to the end of a path parameter. Example: /users/{p+}, where p indicates one or multiple segments between slashes (/). Path parameters contained in the request path must be defined as request parameters. Path is case sensitive.
Matching	Select the matching mode of the API request path. Exact match: The path in an API request must be the same as the value of Path. Prefix match: The path in an API request must be prefixed with the value of Path. Example: If Path is set to /test/AA and Matching is set to Prefix match, the API can be accessed using /test/AA/BB or /test/AA/CC but cannot be accessed using /test/AACC. NOTE: If you set the matching mode to Prefix match, the characters of the API request path excluding the prefix are transparently transmitted to the backend service. Example: If the request path is set to /test and the backend request path is set to /test2, the request path received by the backend service is /test2/AA/CC when /test/AA/CC is used to access the API.
Tags	Add tags for the API for quick search.
Description	Enter a brief description of the API.
Content Format Type	Available for Method set to POST, PUT, or ANY. Determine whether to specify the content format of API requests. The options are application/json, application/xml, text/plain, and multipart/form-data.
Body	Available for Method set to POST, PUT, PATCH, or ANY. Enter the description of the request body in the API request to help the API caller understand how to correctly encapsulate the API request.

Configure API security information.

**Table 2** Security configuration
Parameter	Description
Visibility	Determine whether the API can be listed on KooGallery. Public: The API can be listed on KooGallery. Private: The API cannot be listed on KooGallery even when its API group has been listed.
Authentication Mode	Select the authentication mode of the API. The App authentication mode is recommended. App: ROMA Connect authenticates API requests. When calling an API, a user gets authenticated using the key and secret of an authorized integration application. APIs using this mode can be called by all users. IAM: IAM authenticates API requests. When calling an API, a user gets authenticated using the token or AK/SK. APIs using this mode can be called only by users on the same cloud service platform. Custom: The custom function API is used for authenticating API requests. APIs using this mode can be called by all users. None: Authentication is not required for API requests. APIs using this mode can be called by all users.
Simple Authentication	Available for Authentication Mode set to App. This parameter specifies whether to use simple security authentication for API calling. It takes effect only when the API request protocol is HTTPS. Once enabled, a user gets authenticated using the AppCode when calling an API. Signature verification is not required for API requests.
Two-Factor Authentication	Available for Authentication Mode set to App or IAM. This parameter specifies whether to use a custom function API to authenticate API requests when App or IAM authentication is also enabled. Once enabled, select a frontend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a frontend custom authorizer.
Custom Authorizer	Mandatory for Authentication Mode set to Custom. Select a frontend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a frontend custom authorizer.
CORS	Specifies whether cross-origin resource sharing (CORS) is supported for the API. For security, a browser restricts cross-domain requests initiated from scripts. That is, only resources from the same domain can be requested. However, CORS allows a browser to send XMLHttpRequest requests to a server in a different domain. For details about CORS, see Configuring CORS for APIs.

Configure the request parameters of the API.

Click Add Request Parameter on the Parameters, Headers, and Cookies tab pages to configure API request parameters. Path variables also need to be configured if the API's URL contains path parameters.

**Table 3** Request parameters
Parameter	Description
Parameter Name	Name of the request parameter.
Parameter Type	Data type of the request parameter. Options: STRING or NUMBER
Required	Whether the request parameter must be specified when the API is called. No: enables you to set Default Value.
Passthrough	Whether to transparently transmit the parameter to the backend service.
Enumerated Value	Enumerated value of the parameter. Use commas (,) to separate multiple enumerated values. The value of this parameter can only be one of the enumerated values.
Default Value	Available for Required set to No.
Value Restrictions	If Parameter Type is set to STRING, set the minimum and maximum lengths of the parameter value. If Parameter Type is set to NUMBER, set the minimum and maximum parameter values. Setting both Min. Length/Min. Value and Max. Length/Max. Value to 0 indicates no limit.
Example	Example of a request parameter value.
Description	Description of the request parameter.

The parameter name cannot be x-stage or start with x-apig- or x-sdk- (case insensitive).
For headers, the name is case-insensitive and must be unique. Do not use X-Auth-Token or Authorization for IAM authentication, or Authorization for app authentication.

Click Next.

Defining the Backend

Set the backend type to HTTP&HTTPS, FunctionGraph, or Mock.

If FunctionGraph is not deployed in the current environment, the backend type cannot be set to FunctionGraph.

Configure the basic definition of the default backend. The configuration varies by the backend type selected.

Default backend of the HTTP&HTTPS type

**Table 4** Default backend of the HTTP&HTTPS type
Parameter	Description
Load Balance Channel	Determine whether to use a load balance channel to access backend services. Configure: create a load balance channel in advance.
URL	Configure the URL of the backend service. Method: Select the request method of the backend service. ANY indicates that the backend service can be accessed using any request method. Protocol: Select the request protocol used by the backend service. WebSocket is supported. HTTPS is recommended for transmitting important or sensitive data. Backend Address: Mandatory for Load Balance Channel set to Skip. Enter the access address of the backend service in the format of Host:Port. Host: IP address or domain name for accessing the backend service. If no port is specified, port 80 and 443 is used by default for HTTP and HTTPS respectively. If the backend address needs to contain environment variables, use #Variable name# to add the environment variables to the backend address, for example, #ipaddress#. Multiple environment variables can be added, for example, #ipaddress##test#. If you want to call a custom backend by using its backend request address, add two built-in gateway parameters to system parameters. apiId: Set Backend Parameter Name to x-auth-app and Backend Parameter Location to HEADER. providerAppId: Set Backend Parameter Name to x-ld-appid and Backend Parameter Location to HEADER. Load Balance Channel: Mandatory for Load Balance Channel set to Configure. Select a load balance channel for backend service access. Path: Enter the request path of the backend service. Enclose multiple path parameters by braces. Example: /getUserInfo/{userId} If the path needs to contain an environment variable, enclose the environment variable in number signs (#). Example: /#path# Environment variable names are case sensitive. Multiple environment variables can be added. Example: /#path##request# NOTE: If you have defined environment variables in Path, the API cannot be debugged on the API debugging page. For variables defined in Path, corresponding environment variables and their values must be configured. Otherwise, the API cannot be published because there will be no values that can be assigned to the variables.
Cascading	Available for the instance parameter cascade set to on and Load Balance Channel set to Configure. Whether to use the cascading mode to access backend services. This function must be enabled when API cascading is used.
Host Header	Available for Load Balance Channel set to Configure. Define the Host header field carried in the backend service request.
Timeout (ms)	Enter the timeout interval of a backend service request. Default: 5000
Retries	Number of retries after ROMA Connect fails to call the backend service. -1: The retry function is disabled. However, requests will be retried once by default except for those using POST and PATCH. 0 to 10: This parameter is enabled and will make the configured number of retries. NOTE: If Load Balance Channel is set to Configure, the number of retries must be less than the number of enabled backend servers in the load balance channel.
Two-Way Authentication	Available only if the URL's Protocol is set to HTTPS. Determine whether to enable two-way authentication between ROMA Connect and backend services. If you enable this option, you also need to configure the certificate for client authentication.
Backend Authentication	Specify whether to use a custom authorizer for authentication. Once enabled, select a backend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a backend custom authorizer.

Default backend of the FunctionGraph type

**Table 5** Default backend of the FunctionGraph type
Parameter	Description
Function URN	Enter the ID of a function request. Click Select to add a backend function URN.
Version/Alias	Select the version or alias of the function to be used.
Invocation Mode	Select the invocation type of the function. Synchronous: When receiving a calling request, FunctionGraph immediately processes the request and returns a result. The client closes the connection once it has received a response from the backend. Asynchronous: After receiving a calling request, FunctionGraph queues the request and returns the result after the request is successfully executed. The server processes the queuing requests one by one when it is idle. The client does not care about the calling result.
Timeout (ms)	Enter the timeout interval of a backend service request. The default value is 5000.
Backend Authentication	Specify whether to use a custom authorizer for authentication. Once enabled, select a backend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a backend custom authorizer.

Default backend of the Mock type

**Table 6** Default backend of the Mock type
Parameter	Description
Status Code	Select the HTTP status code returned by the API.
Response	Enter the API response result. Example: Set Response to Successful Info, so the API always returns Successful Info.
Backend Authentication	Specify whether to use a custom authorizer for authentication. Once enabled, select a backend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a backend custom authorizer.
Add Header	Click Add Header to add custom header parameters of the API response.

(Optional) Configure backend parameters to map the request parameters transferred when the API is called to the corresponding location in the backend request. If no request parameter is defined in the API request, skip this step.

In the Backend Parameters area, add backend parameters in either of the following ways:
- Click Import Request Parameter to add all defined API request parameters to the backend parameters.
- Click Add Backend Parameter Mapping to add backend parameters one by one as required.
Modify the mapping between API request parameters and backend parameters.
- The name and location of the backend parameters can be different from those of the input parameters.
- If Backend Parameter Location is PATH, the backend parameter name must be the same as the parameter name configured in Path in the backend URL.
- The backend parameter name cannot be x-stage or start with x-apig- or x-sdk- (case insensitive).
- If Backend Parameter Location is HEADER, the parameter name is case insensitive.

The parameters and backend path in the following table are used as an example. Parameters test01 and test03 are located in PATH and QUERY in an API request. Through parameter mappings, the backend service receives the values of test01 and test03 in HEADER. Parameter test02 is located in HEADER in an API request. Through the parameter mapping, the backend service receives the value of test02 using test05 in PATH.

**Table 7** Example of backend parameter mapping
Request Parameter Name	Request Parameter Location	Backend Parameter Name	Backend Parameter Location
test01	PATH	test01	HEADER
test02	HEADER	test05	PATH
test03	QUERY	test03	HEADER
Backend path: /apitest/{test05}

Assume that test01 is aaa, test02 is bbb, and test03 is ccc.

The API request is as follows:

curl -ik -H 'test02:bbb' -X GET https://example.com/v1.0/aaa?test03=ccc

The backend service request is as follows:

curl -ik -H 'test01:aaa' -H 'test03:ccc' -X GET https://apitest/bbb

(Optional) Configure backend constant parameters. Constant parameters can be defined to receive fixed constants. When sending a request to a backend service, ROMA Connect adds constant parameters to the specified location in the request and then sends the request to the backend service.

In the Constant Parameters area, click Add Constant Parameter to add the constant parameters of the backend service request.

**Table 8** Constant parameters
Parameter	Description
Constant Parameter Name	Enter the name of a constant parameter. If Parameter Location is PATH, the parameter name must be the same as that in the backend URL. NOTE: The parameter name cannot be x-stage or start with x-apig- or x-sdk- (case insensitive). If Location is HEADER, the parameter name is case insensitive.
Parameter Location	Select the location of the constant parameter in the backend service request. Options: PATH, HEADER, QUERY
Parameter Value	Enter the value of the constant parameter.
Description	Enter the description of the constant parameter.

ROMA Connect sends requests containing constant parameters to backend services after percent-encoding of special parameter values. Ensure that the backend services support percent-encoding. For example, parameter value [api] becomes %5Bapi%5D after percent-encoding.
For values of path parameters, ROMA Connect will percent-encode the following characters: ASCII codes 0–31, blank symbols, ASCII codes 127–255, and special characters ?></%#"[\]^`{|}
For values of query parameters, ROMA Connect will percent-encode the following characters: ASCII codes 0–31, blank symbols, ASCII codes 127–255, and special characters >=<+&%#"[\]^`{|}

(Optional) Configure backend system parameters. If a backend service needs to receive parameter information generated during system running, such as gateway built-in parameters, frontend authentication parameters, and backend authentication parameters, you can set system parameters. When sending a request to a backend service, ROMA Connect adds system parameters to the specified location in the request and then sends the request to the backend service.

In the System Parameters area, click Add System Parameter to add the system parameters of the backend service request.

**Table 9** System parameters
Parameter	Description
System Parameter Type	Select the type of a system parameter. Default gateway parameter: system parameters that can be configured for ROMA Connect. Frontend authentication parameter: parameters to be displayed in the frontend custom authentication result. This option is available only if you have set Authentication Mode to Custom in Defining the API Request. Backend authentication parameter: parameters to be displayed in the backend custom authentication result. This option is available only if Backend Authentication is enabled when you configure the basic definition of the default backend.
System Parameter Name	Enter the name of a system parameter. If System Parameter Type is Default gateway parameter, select the parameters that can be obtained by the system. sourceIp: source IP address of the client that calls an API. stage: name of the environment in which the API is published. apiId: ID of the API. appId: ID of the integration application used to call the API. requestId: request ID generated when the API is called. serverAddr: IP address of the gateway server. serverName: name of the gateway server. handleTime: processing time of the called API. providerAppId: ID of the integrated application to which the API belongs. apiName: name of the API. This parameter is available only after the API is published. appName: name of the integration application used to call the API. If System Parameter Type is set to Frontend authentication parameter or Backend authentication parameter, you can define a value for System Parameter Name. However, the customized value must be set in the return result of custom authentication.
Backend Parameter Name	Enter the name of the backend parameter to be mapped. NOTE: The parameter name cannot be x-stage or start with x-apig- or x-sdk- (case insensitive). If Backend Parameter Location is HEADER, the parameter name is case insensitive.
Backend Parameter Location	Select the location of the system parameter in the backend service request. Options: PATH, HEADER, QUERY
Description	Enter the description of the system parameter.

(Optional) Add a backend policy. You can add multiple backend policies for an API as required and set different policy conditions to forward API requests to different backend services.

Click next to Backend Policies to add a backend policy for the API.

Configure information about the backend policy.

Some basic parameters of a backend policy are the same as those of the default backend. For details, see the parameter description for the default backend basic definition. Table 10 describes only the parameters specific to a backend policy.

**Table 10** Parameters for creating a backend policy
Parameter	Description
Name	Enter a backend policy name to identify different backend policies.
Effective Mode	Select the effective mode of the backend policy. Any condition met: If an API request meets any of the conditions in a policy, the request is forwarded to the backend. All conditions met: API requests are forwarded to the backend only when all policy conditions are met.
Policy Conditions	Click Add Policy Condition to add conditions for the policy to take effect. Source: source of the conditions specified in the policy Request parameter: The request parameters set as policy conditions must have already been defined for the API. Source IP address: IP address from which the API is called System parameter: a system parameter that defines system runtime for the API Cookie: cookies of an API request Parameter Name: mandatory only if Source is set to Request parameter, System parameter, or Cookie. When you set Source to Request parameter, select a request parameter that has been defined. When you set Source to Request parameter, select a system parameter. - reqPath: request URL Example: /a/b/c - reqMethod: request method Example: GET When you set Source to Cookie, enter the name of a cookie parameter. Parameter Location: available only if you set Source to Request parameter. Condition Type: mandatory only if you set Source to Request parameter, Cookie, or System parameter. Equal: The request parameter must be equal to the specified value. Enumerated: The request parameter must be equal to any of the enumerated values. Matching: The request parameter must match the regular expression. NOTE: When Source is set to System parameter and Parameter Name to reqMethod, you can set the condition type only to Equal or Enumerated. Condition Value: Enter the value of the judgment condition. If Condition Type is set to Equal, enter a value. If Condition Type is set to Enumerated, enter multiple values and separate them with commas (,). If Condition Type is set to Matching, enter a regular expression, for example, [0-5]. If Source is set to Source IP address, enter one or more IP addresses and separate them with commas (,).

For example, there are three policy conditions whose Source is Request parameter, as listed in Table 11. If the request parameter value is 11, policy A is met. If the request parameter value is 5, policy B is met. If the request parameter value is 15, policy C is met.

**Table 11** Policy parameters
Policy	Condition Type	Condition Value
Policy A	Equal	11
Policy B	Enumerated	1, 2, 5, 8
Policy C	Matching	[13-20]

Configure response examples to help API callers understand the responses to an API request.

**Table 12** Response configuration
Parameter	Description
Example Success Response	Example of a successful response returned when the API is successfully called.
Example Failure Response	Example of a failure response returned when the API fails to be called.

Click Finish.

Creating an API

Prerequisites

Defining the API Request

Defining the Backend

Feedback

Was this page helpful?