Updated on 2022-04-14 GMT+08:00

Modifying an API

Function

This API is used to modify the information about an API, including its backend information.

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

PUT

/v1.0/apigw/apis/{id}

The following table lists the parameter in the URI.

Table 2 Parameter description

Parameter

Mandatory

Type

Description

id

Yes

String

API ID, which can be obtained by querying the API information

Request

Table 3 Parameter description

Parameter

Mandatory

Type

Description

group_id

No

String

ID of the API group to which the API belongs. The value of this parameter cannot be modified.

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

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.
  • WEBSOCKET

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

Dictionary

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

[]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 gateway 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 4 Parameter description of backend_api

Parameter

Mandatory

Type

Description

url_domain

Required when no VPC channel is used.

String

Backend endpoint

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

NOTE:

The value of this parameter must comply with URI specifications.

timeout

Yes

Integer

Timeout duration for API Gateway to request for the backend service. Range: 1–60,000.

Unit: ms.

Default value: 45000. This value will be used if the specified value is outside the allowable range.

remark

No

String

Description of the web backend

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 if vpc_status is set to 1.

Dictionary

VPC channel details

authorizer_id

No

String

ID of the backend custom authorizer

Table 5 VPC channel parameter description

Parameter

Mandatory

Type

Description

vpc_id

Yes

String

VPC channel ID

vpc_proxy_host

No

String

Proxy host

Table 6 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 7 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 API Gateway to request for FunctionGraph. Range: 1–60,000.

Unit: ms.

Default value: 45000. This value will be used if the specified value is outside the allowable range.

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 8 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 9 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 not 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 10 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 API Gateway to request for the backend service. Range: 1–60,000.

Unit: ms.

Default value: 45000. This value will be used if the specified value is outside the allowable range.

vpc_status

No

Integer

Indicates whether to use a VPC channel. The value can be:

  • 1: yes
  • 2: no

vpc_info

Required if 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 11 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 12 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, which can be async or sync

timeout

No

Integer

Timeout duration for API Gateway to request for FunctionGraph. Range: 1–60,000.

Unit: ms.

Default value: 45000. This value will be used if the specified value is outside the allowable range.

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 13 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 14 Parameter description of auth_opt

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": "xxxxxxxxx"
  },
  "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 15 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 is registered

update_time

Timestamp

Time when the API was last modified

remark

String

Description of the API

bakend_type

String

Backend type

run_env_name

String

Name of the environment in which the API has been published

run_env_id

String

ID of the environment in which the API has been published

publish_id

String

ID of the publication record

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 16 Parameter description of backend_api

Parameter

Type

Description

id

String

Web 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

Time when the web backend is registered

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 17 Parameter description of mock_info

Parameter

Type

Description

id

String

Mock backend ID

status

Integer

Mock backend status

version

String

Version of the Mock backend

result_content

String

Mock response

register_time

Timestamp

Time when the Mock backend is registered

update_time

Timestamp

Time when the Mock backend was last modified

remark

String

Description of the Mock backend

Table 18 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

Time when the function is registered

update_time

Timestamp

Time when the function was last updated

timeout

Integer

Timeout duration in milliseconds

remark

String

Description of the function

Table 19 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 20 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 parameter

Table 21 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 22 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 23 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 24 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 25 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": "DISABLE"
  },
  "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
  }]
}

Status Codes

Table 26 Status codes

Status Code

Description

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

500

Server Internal Error