Creating an API_ROMA Connect

Overview

Create APIs to encapsulate existing backend services into standard RESTful APIs and make them accessible to other users.

Prerequisites

Each API must belong to an integration application. Before creating an API, ensure that an integration application is available. Otherwise, create an integration application first.
Each API must belong to an API group. Before creating an API, ensure that the API group is available. Otherwise, create an API group first.
If you need to use a load balance channel to access the ECS where the backend service is located, create a load balance channel first.
If you need to use the custom mode for API security authentication, create a custom authorizer first.

Setting Basic Information

Log in to the ROMA Connect console. On the Instances page, click View Console next to a specific instance.
In the navigation pane, choose API Connect > API Management. On the APIs tab page, click Create API.

On the Create API page, configure basic information about the API.

**Table 1** Basic API information
Parameter	Description
Name	Enter an API name. It is recommended that you enter a name based on naming rules to facilitate search.
Integration Application	Select the integration application to which the API belongs. If no integration application is available, click Create Integration Application on the right to create an integration application.
API Group	Select the API group to which the API belongs. If no API group is available, click Create API Group on the right to create an API group.
Security Authentication	Select the authentication mode of the API. The App authentication mode is recommended. App: ROMA Connect authenticates API requests. When a user calls an API, the key and secret of the integration application are used for authenticating API requests. APIs using this mode can be called by all users. IAM: IAM authenticates API requests. When a user calls an API, the token or AK/SK is used for authenticating API requests. 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	This parameter is available only if Security Authentication is set to App. This parameter specifies whether simple security authentication is used for API calling. This parameter is valid only when the API request protocol is HTTPS. If this parameter is enabled, AppCode is carried for security authentication when an API is called, and signature verification is not required for API requests.
Two-Factor Authentication	This parameter is available only if you have set Security Authentication to App or IAM. This parameter specifies whether to perform two-factor authentication on API calling. If this parameter is selected, the custom function API is also used to authenticate API requests when APP or IAM has been selected for Security Authentication.
Custom Authorizer	This parameter is mandatory only if you have set Security Authentication to App or IAM and have selected Two-Factor Authentication, or only if you have set Security Authentication to Custom. Select a custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a frontend custom authorizer.
Tag Name	Add tags for the API to quickly filter and search for the API.
Description	Enter a brief description of the API.

Click Next.

Defining API Request

Define request information of an API.

**Table 2** API request configuration
Parameter	Description
Request Protocol	Select the request protocol used by the API. The value can be HTTP, HTTPS, or HTTP&HTTPS. HTTPS is recommended for transmitting important or sensitive data.
Path	Enter the request path of the API, in the /getUserInfo/{userId} format. The request path can contain the path parameter in the format of {Parameter name}. The value of the path parameter must match the entire segment between slashes (/). For example, /abc{userId} is not supported. If Matching is set to Exact match, a plus sign (+) can be added to the end of the path parameter, for example, /users/{p+}. The variable p matches the segments between one or multiple pairs of slashes (/). Path parameters contained in the request path must be defined as input parameters. The value of 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. For 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: When Matching is set to Prefix match, the rest characters of the API access address except the matched prefix are transparently transmitted to the backend service. For 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.
Method	Select the request method of the API. ANY indicates that the API can be accessed using any request method.
CORS	This parameter specifies whether CORS is supported for the API. For security purposes, the browser restricts the cross-domain requests from being initiated from a page script. In this case, the page can access only the resources from the same source. CORS allows the browser to send XMLHttpRequest requests to the server in a different domain. For details about CORS, see Configuring CORS for APIs.
(Optional) Input Parameters	Define API request parameters based on the site requirements. Parameters contained in the request path must be defined as input parameters. In the Input Parameters area, click Add Input Parameter and add request parameters of the API. Name: name of a request parameter. If Location is set to PATH, the parameter name must be the same as that in the request path. Location: position of the request parameter in the API request. The value can be PATH, HEADER, or QUERY. Type: data type of the request parameter. The value can be STRING or NUMBER. Mandatory: specifies whether a request parameter is mandatory in an API request. Passthrough: indicates whether to transparently transmit request parameters to the backend service. Default Value: The default value of the request parameter can be set only when Mandatory is set to No. Enumerated Value: enumerated value of the request parameter. The value of the request parameter can only be selected from the enumerated values. Use commas (,) to separate multiple enumerated values. Max. Length/Max. Value: If Type is set to STRING, set this parameter to the maximum character string length as the parameter value. If Type is set to NUMBER, set this parameter to the maximum value as the parameter value. Min.Length/Min.Value: If Type is set to STRING, set this parameter to the minimum string length as the parameter value. If Type is set to NUMBER, set this parameter to the minimum value as the parameter value. Example: example of a request parameter value. Description: description of a request parameter. NOTE: The parameter name is not case-sensitive. It cannot be x-stage or start with x-apig- or x-sdk- If Location is specified as HEADER, ensure that the parameter name is not Authorization or X-Auth-Token and does not contain underscores (_).
Body	This parameter is available only if Method is 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.

Click Next.

Defining Backend Requests

Configure the basic definition of the default backend.

**Table 3** Backend service access parameters
Backend Type	Parameter	Description
HTTP/HTTPS	Protocol	Select the request protocol used by the backend service. WebSocket is supported for HTTP and HTTPS. HTTPS is recommended for transmitting important or sensitive data.
	Method	Select the request method of a backend service. ANY indicates that the backend service can be accessed using any request method.
	Load Balance Channel	This parameter specifies whether to use the load balance channel to access backend services. If you select Configure now, you need to create a load balance channel in advance.
	Backend Address	This parameter is mandatory only if Load Balance Channel is set to Do not configure. Enter the access address of the backend service in the format of Host:Port. Host indicates the IP address or domain name for accessing the backend service. If no port is specified, port 80 is used for HTTP by default, and port 443 is used for HTTPS by default. 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	This parameter is mandatory only if Load Balance Channel is set to Configure now. Select the load balance channel used to access the backend service.
	Host Header	This parameter is available only if Load Balance Channel is set to Configure now. Define the Host header field carried in the backend service request.
	Path	Enter the request path of the backend service, in the /getUserInfo/{userId} format. The request path can contain the path parameter in the format of {Parameter name}. If the path needs to contain an environment variable, enclose the environment variable in number signs (#), for example, /#path#. Multiple environment variables can be added, for example, /#path##request#.
	Timeout (ms)	Enter the timeout interval of a backend service request. The default value is 5000.
	Two-way Authentication	This parameter is mandatory only if 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	Determine whether to enable backend authentication. If this option is enabled, a custom function API is used to perform security authentication on backend service requests.
	Custom Authorizer	This parameter is mandatory only if Backend Authentication is enabled. Select a custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a custom authorizer of the backend type.
Mock	Response	If the backend service is unavailable, you can use the Mock mode to return the expected result to the API caller for debugging and verification. For example, if Response is set to Successful Info, the API always returns Successful Info as the response result no matter what request parameters are set. The Mock mode is generally used in the API development and debugging phase.
	Backend Authentication	Determine whether to enable backend authentication. If this option is enabled, a custom function API is used to perform security authentication on backend service requests.
	Custom Authorizer	This parameter is mandatory only if Backend Authentication is enabled. Select a custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a custom authorizer of the backend type.

If an environment variable is defined in the backend request path, the API cannot be debugged.
For environment variables defined in the backend request path, corresponding variables and their values must be created. Otherwise, the APIs cannot be published because there will be no values that can be assigned to the variables.
Environment variable names are case-sensitive.

(Optional) Configure the backend parameters for the default backend to map the request parameters transferred when the API is called to the corresponding location in the backend service 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 Input 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 in Path.
- The backend parameter name is not case-sensitive. It cannot be x-stage or start with x-apig- or x-sdk-
- If Backend Parameter Location is HEADER, the backend parameter name is case-insensitive and cannot contain underscores (_).

The parameters and backend request 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 HEADER.

Input Parameter Name	Input Parameter Location	Backend Parameter Name	Backend Parameter Location
test01	PATH	test01	HEADER
test02	HEADER	test05	PATH
test03	QUERY	test03	HEADER
Backend request 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://example.com/v1.0/bbb

(Optional) Configure constant parameters of the default backend. 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 4** Constant parameters
Parameter	Description
Name	Enter the name of a constant parameter. If Location is PATH, the parameter name must be the same as that in the backend request path. NOTE: The parameter name is not case-sensitive. It cannot be x-stage or start with x-apig- or x-sdk- If Location is HEADER, the parameter name is case-insensitive and cannot contain underscores (_).
Location	Select the location of the constant parameter in the backend service request. The value can be PATH, HEADER, or QUERY.
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 the following 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 the following percent-encode the following characters: ASCII codes 0–31, blank symbols, ASCII codes 127–255, and special characters >=<+&%#"[\]^`{|}

(Optional) Configure system parameters of the default backend. 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 5** System parameters
Parameter	Description
System Parameter Type	Select the type of a system parameter. Default gateway parameter: 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 Custom is selected for Security Authentication in the step of setting basic information. Backend authentication parameter: Parameters to be displayed in the backend custom authentication result. This option is available only if Backend Authentication is enabled in the step of defining backend request.
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. 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 is not case-sensitive. It cannot be x-stage or start with x-apig- or x-sdk- If Backend Parameter Location is HEADER, the parameter name is case-insensitive and cannot contain underscores (_).
Backend Parameter Location	Select the location of the system parameter in the backend service request. The value can be PATH, HEADER, or 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 Add Backend Policy to add a backend policy for the API.

Configure information about the backend policy.

**Table 6** 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	Add conditions for the backend policy to take effect. Source: source of the judgment condition in the policy. Source IP address: The source IP address of the API request is used as the judgment condition. Input parameter: The input parameter of the API request is used as the judgment condition. Parameter Name: This parameter needs to be specified only if Source is set to Input parameter. Select a defined API input parameter. Condition Type: This parameter needs to be specified only if Source is set to Input parameter. Select the type of the judgment condition. Equal: The condition is met when the request parameter value is equal to the specified value. Enumerated: The condition is met when the request parameter value is equal to any of the enumerated values. Matching: The condition is met when the request parameter value is equal to any value in the regular expression. 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 Input Parameter, as listed in the following table. 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 7** Policy parameters
Policy	Condition Type	Condition Value
Policy A	Equal	11
Policy B	Enumerated	1, 2, 5, 8
Policy C	Matching	[13-20]

Click Next and define the responses.

Defining Responses

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

**Table 8** 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