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 server where the backend service is located, create a load balance channel first.
If you need to use custom API authentication, create a custom authorizer first.
Before creating an API, ensure that the ROMA Connect instance can communicate with the network where your backend service resides.
- Same VPC: The instance can directly access the backend service.
- Two VPCs in the same region: Connect the instance and the backend service using 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 subnet where the backend service resides.
To use FunctionGraph as an API backend service, the user must be assigned the FunctionGraph Administrator role.

Setting Basic Information

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 > 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.
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. NOTE: The API group cannot be changed once set and is bound to the access domain name of the API.
Integration Application	This parameter is available only if the type the API group is set to Global. Select the integration application to which the API belongs. If none is available, click Create Integration Application on the right to create one.
Visibility	Determine whether to make the API available on the marketplace. Public: The API can be made available on the marketplace. Private: The API will not be made available on the marketplace even if the API group to which the API belongs is made available on the marketplace.
Security Authentication	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	This parameter is available only if Security Authentication is 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, AppCodes are included when an API is called, and signature verification is not required for API requests.
Two-Factor Authentication	This parameter is available only if Security Authentication is set to App or IAM. This parameter specifies whether to perform two-way 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 if Security Authentication is set to App or IAM and Two-Factor Authentication is enabled, or if Security Authentication is 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.
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. A URL can have multiple path parameters, each enclosed by braces. Each 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 request 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. 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 a request parameter. NOTE: The parameter name is not case-sensitive. It cannot be x-stage or start with x-apig- or x-sdk-. Ensure that the name of a header parameter is not Authorization or X-Auth-Token (not case-sensitive).
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.

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

**Table 3** API backend service parameters
Backend Type	Parameter	Description
HTTP/HTTPS	Protocol	Select the request protocol used by the backend service. WebSocket communication is supported. 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.
	Use Load Balance Channel	This parameter specifies whether to use the load balance channel to access backend services. If you want to select Yes, create a load balance channel in advance.
	Backend Address	This parameter is mandatory only if Use Load Balance Channel is set to No. 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 Use Load Balance Channel is set to Yes. Select the load balance channel used to access the backend service.
	Cascading Flag	This parameter is available only when cascade is set to on for instance parameter configuration and Use Load Balance Channel is set to Yes. Whether to allow cascading access to backend services. This parameter must be enabled when API cascading is enabled.
	Host Header	This parameter is available only when Use Load Balance Channel is set to Yes. 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. A URL can have multiple path parameters, each enclosed by braces. 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.
	Retry Times	Number of retry times after ROMA Connect fails to call the backend service. If the value is -1, the retry function is disabled. However, requests will be retried once by default except for those using POST and PATCH. If the value ranges from 0 to 10, this parameter is enabled, and retries are performed based on the configured value. NOTE: If Use Load Balance Channel is set to Yes, the number of retries must be less than the number of enabled backend servers in the load balance channel.
	Two-Way Authentication	This parameter is available 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 backend custom authorizer.
FunctionGraph	Function URN	Enter the ID of a function request. Click Add to add a function URN as that of a backend service.
	Version	Select the version of the function to be used.
	Invocation Mode	Select the invocation type of the function. Synchronous: When receiving an invocation request, FunctionGraph processes the request immediately and returns a result. The client closes the connection once receiving 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	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 backend custom authorizer.
Mock NOTE: 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.	Status Code	Select the HTTP status code returned by the API.
	Response	Enter the API response result. For example, if Response is set to Successful Info, the API always returns Successful Info.
	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 backend custom authorizer.
	Response Header	Customize the response header information of the API response. Click Add Response Header and enter the parameter name, value, and description.

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 parameter name is not case-sensitive.

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

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://apitest/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 not case-sensitive.
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 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 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. 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 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 not case-sensitive.
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. Condition: conditions specified in the policy Source IP address: IP address from which the API is called Input parameter: input parameter of an API request System parameter: runtime parameter used by API Gateway to process API requests COOKIE: cookies of an API request NOTICE: Input parameters (for example, headers) set as policy conditions must have already been defined in the API request settings. Parameter Name When setting Source to Input parameter, select an input parameter. When setting Source to System parameter, select a system parameter. reqPath: Request URI, for example, /a/b/c. reqMethod: Request method, for example, GET. If Source is set to COOKIE, enter the parameter name. Parameter Location: The parameter location is displayed only if you set Source to Input parameter. Condition Type: This parameter is mandatory only when you set Condition to Input 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 be equal to any value of 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: value of the 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	[0-5]

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