Creating an API

Function

This API is used to register an API. API is an interface that encapsulates a set of service capabilities.

The definition of an API is divided into two parts. One part defines how the API is called by users, and the other part defines how APIG accesses the actual backend service requested by users.

APIG supports three backend types: HTTP/HTTPS web, FunctionGraph, and Mock.

URI

The following table lists the HTTP/HTTPS request method and URI of the API.

**Table 1** HTTP/HTTPS request method and URI
Request Method	URI
POST	/v1.0/apigw/apis

Request

**Table 2** Parameter description
Parameter	Mandatory	Type	Description
group_id	Yes	String	ID of the API group to which the API to be created will belong
name	Yes	String	API name An API name consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.
type	Yes	Integer	Indicates whether the API is available to the public. The value can be: 1: public 2: private
version	No	String	Version of the API A maximum of 16 characters are allowed.
req_protocol	No	String	Request protocol, which can be: HTTP HTTPS BOTH: The API can be accessed through both HTTP and HTTPS. Default value: HTTPS
req_method	Yes	String	Request method, which can be: GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	Yes	String	Access address NOTE: The value of this parameter must comply with URI specifications.
match_mode	No	String	Route matching mode, which can be: SWA: prefix match NORMAL: exact match Default value: NORMAL
remark	No	String	Description of the API The description cannot exceed 255 characters.
auth_type	Yes	String	Security authentication mode, which can be: NONE APP IAM AUTHORIZER
auth_opt	No	AuthOpt object	Security authentication mode parameter
authorizer_id	No	String	ID of the frontend custom authorizer
backend_type	Yes	String	Backend type, which can be: HTTP: web backend FUNCTION: FunctionGraph backend MOCK: Mock backend
tag	No	String	Service name tag This field will be discarded.
tags	No	Array of string	API tags Optional. This parameter contains a service name tag and other tags. The service name tag must start with APIG-SN-. Other tags cannot start with APIG-SN-.
cors	No	Bool	Indicates whether CORS is supported. TRUE: supported FALSE: not supported Default value: FALSE
body_remark	No	String	Description of the API request body, which can be an example request body, media type, or parameter information The description cannot exceed 20,480 characters.
result_normal_sample	No	String	Example response for a successful request The length cannot exceed 20,480 characters.
result_failure_sample	No	String	Example response for a failed request The length cannot exceed 20,480 characters.
response_id	No	String	ID of the custom response
backend_api	Required if backend_type is set to HTTP.	Dictionary	Web backend details
mock_info	Required if backend_type is set to MOCK.	Dictionary	Mock backend details
func_info	Required if backend_type is set to FUNCTION.	Dictionary	FunctionGraph backend details
req_params	No	Dictionary	Request parameter list
backend_params	No	Dictionary	Backend parameter list
policy_https	Optional if backend_type is set to HTTP.	Dictionary	Web backend policy list
policy_mocks	Optional if backend_type is set to MOCK.	Dictionary	Mock backend policy list
policy_functions	Optional if backend_type is set to FUNCTION.	Dictionary	FunctionGraph backend policy list

**Table 3** Parameter description of backend_api
Parameter	Mandatory	Type	Description
url_domain	Required when no VPC channel is used.	String	Backend service address An endpoint URL is in the format of "domain name (or IP address):port number", with up to 255 characters. For example, apig.example.com:7443. By default, the port number would be 443 for HTTPS or 80 for HTTP if it is not specified. An endpoint can contain environment variables, each starting with a letter and consisting of 3–32 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed in environment variables.
version	No	String	Web backend version A maximum of 16 characters are allowed.
req_protocol	Yes	String	Request protocol, which can be: HTTP HTTPS
req_method	Yes	String	Request method, which can be: GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	Yes	String	Request address A request address can contain up to 512 characters and must comply with URI specifications. The request address can contain environment variables, each starting with a letter and consisting of 3–32 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed in environment variables. NOTE: The value of this parameter must comply with URI specifications.
timeout	Yes	Integer	Timeout duration for APIG to request for the backend service. Range: 1–60,000. Unit: ms.
remark	No	String	Description of the backend service The description cannot exceed 255 characters.
vpc_status	No	Integer	Indicates whether to use a VPC channel. The value can be: 1: yes 2: no
vpc_info	Required when vpc_status is set to 1.	Dictionary	VPC channel details
authorizer_id	No	String	ID of the backend custom authorizer

**Table 4** VPC channel parameter description
Parameter	Mandatory	Type	Description
vpc_id	Yes	String	VPC channel ID
vpc_proxy_host	No	String	Proxy host

**Table 5** Parameter description of mock_info
Parameter	Mandatory	Type	Description
result_content	No	String	Mock response
version	No	String	Version of the Mock backend A maximum of 64 characters are allowed.
remark	No	String	Description of the Mock backend The description cannot exceed 255 characters.

**Table 6** Parameter description of func_info
Parameter	Mandatory	Type	Description
function_urn	Yes	String	Function URN
invocation_type	Yes	String	Invocation mode, which can be async or sync
timeout	Yes	Integer	Timeout duration for APIG to request for FunctionGraph. Range: 1–60,000. Unit: ms.
version	No	String	Function version A maximum of 64 characters are allowed.
remark	No	String	Description of the function The description cannot exceed 255 characters.

**Table 7** Parameter description of req_params
Parameter	Mandatory	Type	Description
name	Yes	String	Parameter name A parameter name consists of 1–32 characters, starting with a letter. Only letters, digits, periods (.), hyphens (-), and underscores (_) are allowed.
type	Yes	String	Parameter type, which can be: STRING NUMBER
location	Yes	String	Parameter location, which can be: PATH QUERY HEADER
default_value	No	String	Default value
sample_value	No	String	Example value
required	No	Integer	Indicates whether the parameter is mandatory. 1: yes 2: no The value of this parameter is 1 if Location is set to PATH and 2 if Location is set to another value.
valid_enable	No	Integer	Indicates whether validity check is enabled. 1: enabled 2: disabled The default value is 2.
remark	No	String	Description of the parameter The description cannot exceed 255 characters.
enumerations	No	String	Enumerated value
min_num	No	Integer	Minimum value, which is valid when the parameter type is NUMBER
max_num	No	Integer	Maximum value, which is valid when the parameter type is NUMBER
min_size	No	Integer	Minimum length
max_size	No	Integer	Maximum length
regular	No	String	Regular verification rule (currently not supported)
json_schema	No	String	JSON verification rule (currently not supported)

**Table 8** Parameter description of backend_params
Parameter	Mandatory	Type	Description
name	Yes	String	Parameter name A parameter name consists of 1–32 characters, starting with a letter. Only letters, digits, periods (.), hyphens (-), and underscores (_) are allowed.
location	Yes	String	Parameter location, which can be: PATH QUERY HEADER
origin	Yes	String	Parameter type, which can be: REQUEST CONSTANT SYSTEM
value	Yes	String	Parameter value, which can contain no more than 255 characters If origin is set to REQUEST, the value is the parameter name in req_params. If origin is set to CONSTANT, the value is the real value of the backend parameter. If origin is set to SYSTEM, the value is the name of the gateway parameter.
remark	No	String	Description of the parameter The description cannot exceed 255 characters.

**Table 9** Parameter description of policy_https
Parameter	Mandatory	Type	Description
name	Yes	String	Backend name A backend name consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.
url_domain	Required when no VPC channel is used.	String	Endpoint of the policy backend An endpoint consists of a domain name or IP address and a port number, with not more than 255 characters. It must be in the format "Domain name:Port number", for example, apig.example.com:7443. By default, the port number would be 443 for HTTPS or 80 for HTTP if it is not specified. An endpoint can contain environment variables, each starting with a letter and consisting of 3–32 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed in environment variables.
req_protocol	Yes	String	Request protocol, which can be: HTTP HTTPS
req_method	Yes	String	Request method, which can be: GET POST PUT DELETE HEAD PATCH OPTIONS ANY
req_uri	Yes	String	Request address A request address can contain up to 512 characters and must comply with URI specifications. The request address can contain environment variables, each starting with a letter and consisting of 3–32 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed in environment variables. NOTE: The value of this parameter must comply with URI specifications.
timeout	No	Integer	Timeout duration for APIG to request for the backend service. Range: 1–60,000. Unit: ms.
vpc_status	No	Integer	Indicates whether to use a VPC channel. The value can be: 1: yes 2: no
vpc_info	Required when vpc_status is set to 1.	Dictionary	VPC channel details
effect_mode	Yes	String	Effective mode of the backend policy ALL ANY
conditions	Yes	Dictionary	Policy condition list
backend_params	No	Dictionary	Backend parameter list

**Table 10** Parameter description of policy_mocks
Parameter	Mandatory	Type	Description
name	Yes	String	Backend name A backend name consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.
result_content	No	String	Mock response
effect_mode	Yes	String	Effective mode of the backend policy ALL ANY
conditions	Yes	Dictionary	Policy condition list
backend_params	No	Dictionary	Backend parameter list

**Table 11** Parameter description of policy_functions
Parameter	Mandatory	Type	Description
name	Yes	String	Backend name A backend name consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.
function_urn	Yes	String	Function URN
invocation_type	Yes	String	Invocation mode. Options: async: asynchronous sync: synchronous
timeout	No	Integer	Timeout duration for APIG to request for FunctionGraph. Range: 1–60,000. Unit: ms.
version	No	String	Function version A maximum of 64 characters are allowed.
effect_mode	Yes	String	Effective mode of the backend policy ALL ANY
conditions	Yes	Dictionary	Policy condition list
backend_params	No	Dictionary	Backend parameter list

**Table 12** Parameter description of conditions
Parameter	Mandatory	Type	Description
condition_type	Mandatory if the policy type is param.	String	Condition type. Options: exact: Exact match enum: Enumeration pattern: Regular expression
condition_value	Yes	String	Condition value
condition_origin	Yes	String	Condition source. Options: param: Input parameter source: Source IP address
req_param_name	Mandatory if the policy type is param.	String	Input parameter name

**Table 13** AuthOpt
Parameter	Mandatory	Type	Description
app_code_auth_type	No	String	Indicates whether AppCode authentication is enabled. This parameter is valid only when auth_type is set to App. The default value is DISABLE. DISABLE: AppCode authentication is disabled. HEADER: AppCode authentication is enabled and the AppCode is located in the header.

Example request:

{
  "auth_type": "app",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "backend_api": {
    "req_method": "get",
    "req_protocol": "http",
    "req_uri": "/test",
    "timeout": 1000,
    "url_domain": "xxxxxxxxxxx"
  },
  "backend_params": [
    {
      "location": "query",
      "name": "project_id",
      "origin": "request",
      "value": "project_id"
    },
    {
      "location": "query",
      "name": "city",
      "origin": "request",
      "value": "city"
    }
  ],
  "backend_type": "http",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "name": "test",
  "req_method": "get",
  "req_params": [
    {
      "location": "path",
      "name": "project_id",
      "required": 1,
      "type": "string"
    },
    {
      "location": "query",
      "name": "city",
      "required": 2,
      "type": "string"
    }
  ],
  "req_uri": "/test/{project_id}",
  "tags": ["APIG-SN-test", "test"],
  "type": 1,
  "result_normal_sample": "hello world!"
}

Response

**Table 14** Parameter description
Parameter	Type	Description
id	String	API ID
name	String	API name
group_id	String	ID of the API group to which the API belongs
group_name	String	Name of the API group to which the API belongs
status	Integer	API status
type	Integer	API type
version	String	API version
req_protocol	String	Request protocol
req_method	String	Request method
req_uri	String	Access address
auth_type	String	Security authentication mode
auth_opt	Object	Security authentication mode parameter
match_mode	String	Matching mode
register_time	Timestamp	Time when the API was created
update_time	Timestamp	Time when the API was last modified
remark	String	API description
bakend_type	String	Backend type
arrange_necessary	Integer	Indicates whether orchestration is required.
tag	String	Service name tag, which is to be discarded
tags	[]String	API tags
cors	Bool	Indicates whether CORS is supported.
body_remark	String	Description of the API request body, which can be an example request body, media type, or parameter information
result_normal_sample	String	Example response for a successful request
result_failure_sample	String	Example response for a failed request
response_id	String	ID of the gateway response
backend_api	Dictionary	Web backend details
mock_info	Dictionary	Mock backend details
func_info	Dictionary	FunctionGraph backend details
req_params	Dictionary	Request parameter list
backend_params	Dictionary	Backend parameter list
policy_https	Dictionary	Web backend policy list
policy_mocks	Dictionary	Mock backend policy list
policy_functions	Dictionary	FunctionGraph backend policy list

**Table 15** Parameter description of backend_api
Parameter	Type	Description
id	String	Backend ID
status	Integer	Web backend status
url_domain	String	Backend endpoint
version	String	Web backend version
req_protocol	String	Request protocol
req_method	String	Request method
req_uri	String	Access address
timeout	Integer	Timeout duration in milliseconds
register_time	Timestamp	Creation time
update_time	Timestamp	Time when the web backend was last modified
remark	String	Description of the web backend
vpc_status	String	Indicates whether to use a VPC channel.
vpc_info	String	VPC channel information

**Table 16** Parameter description of mock_info
Parameter	Type	Description
id	String	Mock backend ID
status	Integer	Mock backend status
version	String	Mock backend version
result_content	String	Mock response
register_time	Timestamp	Creation time
update_time	Timestamp	Time when the Mock backend was last modified
remark	String	Description of the Mock backend

**Table 17** Parameter description of func_info
Parameter	Type	Description
id	String	Function ID
status	Integer	Function status
version	String	Function version
function_urn	String	Function URN
invocation_type	String	Invocation mode, which can be async or sync
register_time	Timestamp	Creation time
update_time	Timestamp	Time when the function was last updated
timeout	Integer	Timeout duration in milliseconds
remark	String	Description of the function

**Table 18** Parameter description of req_params
Parameter	Type	Description
id	String	Parameter ID
name	String	Parameter name
type	String	Parameter type
location	String	Parameter location
default_value	String	Default value
sample_value	String	Example value
required	Integer	Indicates whether the parameter is mandatory.
valid_enable	Integer	Indicates whether validity check is enabled.
remark	String	Description of the parameter
enumerations	String	Enumerated value
min_num	Integer	Minimum value, which is valid when the parameter type is NUMBER
max_num	Integer	Maximum value, which is valid when the parameter type is NUMBER
min_size	Integer	Minimum length
max_size	Integer	Maximum length
regular	String	Regular verification rule (currently not supported)
json_schema	String	JSON verification rule (currently not supported)

**Table 19** Parameter description of backend_params
Parameter	Type	Description
id	String	Parameter ID
req_param_id	String	ID of the request parameter to which the backend parameter is mapped
name	String	Parameter name
location	String	Parameter location
origin	String	Parameter type
value	String	Parameter value
remark	String	Description of the backend parameter

**Table 20** Parameter description of policy_https
Parameter	Type	Description
id	String	Backend policy ID
name	String	Backend name
url_domain	String	Endpoint of the policy backend
req_protocol	String	Request protocol
req_method	String	Request method
req_uri	String	Access address
timeout	Integer	Timeout duration in milliseconds
vpc_status	String	Indicates whether to use a VPC channel.
vpc_info	String	VPC channel information
effect_mode	String	Effective mode of the backend policy
conditions	Dictionary	Policy condition list
backend_params	Dictionary	Backend parameter list

**Table 21** Parameter description of policy_mocks
Parameter	Type	Description
id	String	Backend policy ID
name	String	Backend name
result_content	String	Mock response
effect_mode	String	Effective mode of the backend policy
conditions	Dictionary	Policy condition list
backend_params	Dictionary	Backend parameter list

**Table 22** Parameter description of policy_functions
Parameter	Type	Description
id	String	Backend policy ID
name	String	Backend name
version	String	Function version
function_urn	String	Function URN
invocation_type	String	Invocation mode, which can be async or sync
timeout	Integer	Timeout duration in milliseconds
effect_mode	String	Effective mode of the backend policy
conditions	Dictionary	Policy condition list
backend_params	Dictionary	Backend parameter list

**Table 23** Parameter description of conditions
Parameter	Type	Description
id	String	Backend policy condition ID
condition_type	String	Condition type
condition_value	String	Condition value
condition_origin	String	Condition source
req_param_name	String	Input parameter name
req_param_id	String	Input parameter ID
req_param_location	String	Input parameter location

**Table 24** Parameter description of auth_opt
Parameter	Type	Description
app_code_auth_type	String	Indicates whether AppCode authentication is enabled.

Example response:

{
  "name": "test",
  "type": 1,
  "version": "V0.0.1",
  "req_protocol": "HTTPS",
  "req_method": "GET",
  "req_uri": "/test/{tenant_id}",
  "auth_type": "APP",
  "auth_opt": {
    "app_code_auth_type": "HEADER"
  },
  "tags": ["APIG-SN-test", "test"],
  "cors": false,
  "match_mode": "NORMAL",
  "backend_type": "HTTP",
  "group_id": "f71f69876f90456ca6fd18ed012fdc11",
  "result_normal_sample": "hello world!",
  "id": "81efcfd94b8747a0b21e8c04144a4e8c",
  "status": 1,
  "arrange_necessary": 2,
  "register_time": "2018-08-15T03:41:11.0239936Z",
  "update_time": "2018-08-15T03:41:11.0239936Z",
  "group_name": "group0002",
  "backend_api": {
    "url_domain": "xxxxxxxxxxx",
    "req_protocol": "HTTP",
    "req_method": "GET",
    "req_uri": "/test",
    "timeout": 1000,
    "vpc_status": 2,
    "id": "3442ffd031814e3a8f133a9f1ea08453",
    "status": 1,
    "register_time": "2018-08-15T03:41:11.1019236Z",
    "update_time": "2018-08-15T03:41:11.1019236Z"
  },
  "req_params": [
    {
      "name": "tenant_id",
      "type": "STRING",
      "location": "PATH",
      "required": 1,
      "valid_enable": 2,
      "id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "type": "STRING",
      "location": "QUERY",
      "required": 2,
      "valid_enable": 2,
      "id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "backend_params": [
    {
      "name": "tenant_id",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "tenant_id",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    },
    {
      "name": "city",
      "location": "QUERY",
      "origin": "REQUEST",
      "value": "city",
      "id": "b60fbcb5b86f4f5c8705c445b9bd6325",
      "req_param_id": "e0b91bc81ae54f8ea850848d782d6e1e"
    }
  ],
  "policy_https": [{
    "conditions": [{
      "id": "44e03de2351e43a8b18ba9ec1e71d2e9",
      "condition_type": "pattern",
      "condition_value": "^[0-9]$",
      "condition_origin": "param",
      "req_param_name": "project_id",
      "req_param_id": "b60fbcb5b86f4f5c8705c445b9sda325",
      "req_param_location": "PATH"
    }],
    "backend_params": [{
      "name": "project_id",
      "value": "bbbb",
      "location": "QUERY",
      "origin": "REQUEST",
      "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
      "req_param_id": "593c5560e0924e00af08fb458f850ecb"
    }],
    "effect_mode": "ANY",
    "id": "44e03de2351e43a8b18ba9ec1e71d2e8",
    "name": "policy001",
    "req_method": "GET",
    "req_protocol": "http",
    "req_uri": "/test/policy",
    "timeout": 10000,
    "url_domain": "xxxxxxxxxxx",
    "vpc_status": 2
  }]
}