Use ALIYUN::ApiGateway::Api to create an API - Resource Orchestration Service

ALIYUN::ApiGateway::Api is used to create an API.

Syntax

{
  "Type": "ALIYUN::ApiGateway::Api",
  "Properties": {
    "ErrorCodeSamples": List,
    "Description": String,
    "ServiceConfig": Map,
    "SystemParameters": List,
    "ServiceParameters": List,
    "OpenIdConnectConfig": Map,
    "RequestConfig": Map,
    "AuthType": String,
    "Visibility": String,
    "Tags": List,
    "ResultSample": String,
    "ResultType": String,
    "ApiName": String,
    "FailResultSample": String,
    "DisableInternet": Boolean,
    "ForceNonceCheck": Boolean,
    "ConstParameters": List,
    "GroupId": String,
    "ServiceParametersMap": List,
    "RequestParameters": List,
    "AppCodeAuthType": String,
    "ResultBodyModel": String,
    "AllowSignatureMethod": String,
    "WebSocketApiType": String,
    "ResultDescriptions": String
  }
}

Properties

Property	Type	Required	Editable	Description	Constraint
ApiName	String	Yes	Yes	The API name.	The name must be 4 to 50 characters in length and can contain letters, digits, and underscores (_). The name must start with a letter. Note The name must be unique in an API group.
GroupId	String	Yes	No	The ID of the API group.	None.
RequestConfig	Map	Yes	Yes	The configurations of API requests that are sent from the consumer to API Gateway.	For more information, see RequestConfig properties.
ResultSample	String	No	Yes	The sample response from the backend service.	None.
ResultType	String	No	Yes	The format of the response from the backend service.	Valid values: JSON (default) TEXT BINARY XML PASSTHROUGH
ServiceConfig	Map	Yes	Yes	The configurations of API requests that are sent from API Gateway to the backend service.	For more information, see ServiceConfig properties.
Visibility	String	Yes	Yes	Specifies whether the API is public.	Valid values: PUBLIC PRIVATE
AllowSignatureMethod	String	No	Yes	The signature algorithm used when AuthType is set to APP.	Valid values: HmacSHA256 (default) HmacSHA1
AppCodeAuthType	String	No	Yes	The AppCode authentication method.	This property takes effect only if you set AuthType to APP. Valid values: DEFAULT (default): AppCode authentication is configured with the API group. DISABLE: AppCode authentication is disabled. HEADER: AppCode can be placed in Header for authentication. HEADER_QUERY: AppCode can be placed in Header or Query for authentication.
AuthType	String	No	Yes	The security authentication method of the API.	Valid values: APP: The API can be called only by authorized applications. ANONYMOUS: The API can be called anonymously. API Gateway does not authenticate callers and cannot set user-specific throttling policies. Before you publish an API group that contains such APIs in Alibaba Cloud Marketplace, we recommend that you move the APIs to another API group, set Visibility to PRIVATE, or set AuthType to APP. APPOPENID: The API can be called only by applications that are authorized by OpenID Connect. If you set this property to APPOPENID, OpenIdConnectConfig is required.
ConstParameters	List	No	Yes	The constant parameters of the API.	For more information, see ConstParameters properties.
Description	String	No	Yes	The description of the API.	The description can be up to 180 characters in length.
DisableInternet	Boolean	No	Yes	Specifies whether to block Internet-based calls on the API.	Valid values: true false
ErrorCodeSamples	List	No	Yes	The sample error codes that are returned from the backend service.	For more information, see ErrorCodeSamples properties.
FailResultSample	String	No	Yes	The sample error response from the backend service.	None.
ForceNonceCheck	Boolean	No	Yes	Specifies whether to forcefully check X-Ca-Nonce when the request is sent.	Valid values: true false
OpenIdConnectConfig	Map	No	Yes	The configurations of the third-party OpenID Connect authentication method.	For more information, see OpenIdConnectConfig properties.
RequestParameters	List	No	Yes	The parameters of API requests that are sent from the consumer to API Gateway.	For more information, see RequestParameters properties.
ResultBodyModel	String	No	Yes	The response of the API.	None.
ResultDescriptions	String	No	Yes	The description of the response.	None.
ServiceParameters	List	No	Yes	The parameters of API requests that are sent from API Gateway to the backend service.	For more information, see ServiceParameters properties.
ServiceParametersMap	List	No	Yes	The mappings between the parameters of requests sent from the consumer to API Gateway and the parameters of requests sent from API Gateway to the backend service.	For more information, see ServiceParametersMap properties.
SystemParameters	List	No	Yes	The system parameters of the API.	For more information, see SystemParameters properties.
Tags	List	No	Yes	The tags of the API.	You can add up to 20 tags to the API. For more information, see Tags properties.
WebSocketApiType	String	No	Yes	The type of the bidirectional communication API.	Valid values: COMMON: common API REGISTER: registered API UNREGISTER: unregistered API NOTIFY: downstream notification API

Tags syntax

"Tags": [
  {
    "Key": String,
    "Value": String
  }
]

Tags properties

Property	Type	Required	Editable	Description	Constraint
Key	String	Yes	No	The tag key.	The tag key must be 1 to 128 characters in length and cannot contain `http://` or `https://`. The tag key cannot start with `aliyun` or `acs:`.
Value	String	No	No	The tag value.	The tag value can be up to 128 characters in length and cannot contain `http://` or `https://`. The tag value cannot start with `aliyun` or `acs:`.

ErrorCodeSamples syntax

"ErrorCodeSamples": [
  {
    "Message": String,
    "Code": String,
    "Description": String
  }
]

ErrorCodeSamples properties

Property	Type	Required	Editable	Description	Constraint
Code	String	Yes	Yes	The error code.	None.
Message	String	Yes	Yes	The error message.	None.
Description	String	No	Yes	The error description.	None.

ServiceConfig syntax

"ServiceConfig": {
  "ServiceTimeOut": Integer,
  "FunctionComputeConfig": Map,
  "VpcConfig": Map,
  "MockResult": String,
  "MockStatusCode": Integer,
  "ServiceHttpMethod": String,
  "ServiceProtocol": String,
  "ServiceVpcEnable": String,
  "ServiceAddress": String,
  "ContentTypeValue": String,
  "MockHeaders": List,
  "ContentTypeCatagory": String,
  "ServicePath": String,
  "Mock": String
}

ServiceConfig properties

Property	Type	Required	Editable	Description	Constraint
ContentTypeCatagory	String	No	Yes	The ContentType header type that is used when you call the backend service over HTTP.	Valid values: DEFAULT: default header in API Gateway CUSTOM: custom header CLIENT (default): the ContentType header of the client
ContentTypeValue	String	No	Yes	The value of the ContentType header when ServiceProtocol is set to HTTP and ContentTypeCatagory is set to DEFAULT or CUSTOM.	None.
FunctionComputeConfig	Map	No	Yes	The configurations of Function Compute that is used as the backend service.	None. For more information, see FunctionComputeConfig properties.
Mock	String	No	Yes	Specifies whether to use the mock mode.	Valid values: TRUE FALSE (default)
MockHeaders	List	No	Yes	The mock response headers defined when the mock mode is enabled.	None. For more information, see MockHeaders properties.
MockResult	String	No	Yes	The result that is returned when the mock mode is used.	None.
MockStatusCode	Integer	No	Yes	The status code.	The status code is returned in a format that is compatible with HTTP/1.1.
ServiceAddress	String	No	Yes	The URL of the backend service.	If the complete URL of the backend service is `http://example.com:8080/object/add?key1=value1&key2=value2`, the URL of the backend service is `http://example.com:8080`.
ServiceHttpMethod	String	No	Yes	The HTTP method used to call the backend service.	Valid values: GET (default) POST DELETE PUT HEAD TRACE PATCH CONNECT OPTIONS ANY
ServicePath	String	No	Yes	The path of the backend service.	If the complete URL of the backend service is `http://example.com:8080/object/add?key1=value1&key2=value2`, the path of the backend service is `/object/add`.
ServiceProtocol	String	No	Yes	The protocol of the backend service.	Valid values: HTTP HTTPS FunctionCompute
ServiceTimeOut	Integer	No	Yes	The timeout period of the backend service.	Unit: milliseconds.
ServiceVpcEnable	String	No	Yes	Specifies whether to enable the Virtual Private Cloud (VPC) service.	Valid values: TRUE FALSE (default)
VpcConfig	Map	No	Yes	The configurations when the VPC channel is enabled.	For more information, see VpcConfig properties.

VpcConfig syntax

"VpcConfig": {
  "InstanceId": String,
  "VpcId": String,
  "Port": Integer
}

VpcConfig properties

Property	Type	Required	Editable	Description	Constraint
InstanceId	String	Yes	Yes	The ID of the instance in the VPC.	Only Elastic Compute Service (ECS) instances and Server Load Balancer(SLB) instances are supported.
Port	Integer	Yes	Yes	The port number of the instance.	None.
VpcId	String	Yes	Yes	The VPC ID.	None.

SystemParameters syntax

"SystemParameters": [
  {
    "DemoValue": String,
    "ParameterName": String,
    "ServiceParameterName": String,
    "Location": String,
    "Description": String
  }
]

SystemParameters properties

Property	Type	Required	Editable	Description	Constraint
Location	String	Yes	Yes	The location of the system parameter.	None.
ParameterName	String	Yes	Yes	The name of the system parameter.	Valid values: CaClientIp CaDomain CaRequestHandleTime CaAppId CaRequestId CaHttpSchema CaProxy
ServiceParameterName	String	Yes	Yes	The name of the backend parameter.	None.
DemoValue	String	No	Yes	The sample value of the system parameter.	None.
Description	String	No	Yes	The description of the system parameter.	None.

ServiceParameters syntax

"ServiceParameters": [
  {
    "ParameterType": String,
    "Location": String,
    "ServiceParameterName": String
  }
]

ServiceParameters properties

Property	Type	Required	Editable	Description	Constraint
Location	String	Yes	Yes	The location of the backend parameter.	Valid values: BODY HEAD QUERY PATH
ParameterType	String	Yes	Yes	The data type of the backend parameter.	Valid values: STRING NUMBER BOOLEAN
ServiceParameterName	String	Yes	Yes	The name of the backend parameter.	None.

OpenIdConnectConfig syntax

"OpenIdConnectConfig": {
  "OpenIdApiType": String,
  "PublicKey": String,
  "PublicKeyId": String,
  "IdTokenParamName": String
}

OpenIdConnectConfig properties

Property	Type	Required	Editable	Description	Constraint
OpenIdApiType	String	Yes	Yes	The authorization type of the OpenID Connect API.	Valid values: IDTOKEN: obtains an authorization API before issuing a token. If you set this property to IDTOKEN, PublicKeyId and PublicKey are required. BUSINESS: obtains a business API before verifying a token. If you set this property to BUSINESS, IdTokenParamName is required.
IdTokenParamName	String	No	Yes	The name of the parameter that corresponds to the token.	None.
PublicKey	String	No	Yes	The public key.	None.
PublicKeyId	String	No	Yes	The ID of the public key.	None.

RequestConfig syntax

"RequestConfig": {
  "RequestMode": String,
  "RequestPath": String,
  "PostBodyDescription": String,
  "RequestProtocol": String,
  "RequestHttpMethod": String,
  "BodyFormat": String
}

RequestConfig properties

Property	Type	Required	Editable	Description	Constraint
RequestHttpMethod	String	Yes	Yes	The API request method.	Valid values: GET (default) POST DELETE PUT HEADER TRACE PATCH OPTIONS
RequestMode	String	Yes	Yes	The request mode.	Valid values: MAPPING (default): request parameter mapping PASSTHROUGH: request parameter passthrough
RequestPath	String	Yes	Yes	The request path.	If the complete URL of the API is `http://example.com:8080/object/add?key1=value1&key2=value2`, the request path is `/object/add`.
RequestProtocol	String	Yes	Yes	The protocol type that is supported by the API.	Valid values: HTTP HTTPS Separate multiple protocol types with commas (,). Example: `HTTP,HTTPS`.
BodyFormat	String	No	Yes	The format in which data is transmitted to the server for a POST, PUT, or PATCH request.	Valid values: FORM STREAM This property takes effect only if the RequestMode parameter is set to MAPPING.
PostBodyDescription	String	No	Yes	The description of the request body.	None.

ServiceParametersMap syntax

"ServiceParametersMap": [
  {
    "RequestParameterName": String,
    "ServiceParameterName": String
  }
]

ServiceParametersMap properties

Property	Type	Required	Editable	Description	Constraint
RequestParameterName	String	Yes	Yes	The name of the frontend parameter.	The value of this property must be included in RequestParameters and must match the value of ApiParameterName in RequestParameters.
ServiceParameterName	String	Yes	Yes	The name of the backend parameter.	None.

RequestParameters syntax

"RequestParameters": [
  {
    "ParameterType": String,
    "Required": String,
    "Description": String,
    "DemoValue": String,
    "MinLength": Integer,
    "DefaultValue": String,
    "RegularExpression": String,
    "MaxValue": Integer,
    "MinValue": Integer,
    "JsonScheme": String,
    "ApiParameterName": String,
    "Location": String,
    "DocShow": String,
    "MaxLength": Integer,
    "EnumValue": String,
    "DocOrder": Integer
  }
]

RequestParameters properties

Property	Type	Required	Editable	Description	Constraint
ApiParameterName	String	Yes	Yes	The parameter name.	None.
Location	String	Yes	Yes	The parameter location.	Valid values: BODY HEAD QUERY PATH
ParameterType	String	Yes	No	The parameter type.	Valid values: String Int Long Float Double Boolean
Required	String	Yes	Yes	Specifies whether the parameter is required.	Valid values: REQUIRED OPTIONAL
DefaultValue	String	No	Yes	The default value of the parameter.	None.
DemoValue	String	No	Yes	The sample value of the parameter.	None.
Description	String	No	Yes	The description of the parameter.	None.
DocOrder	Integer	No	Yes	The sequence of the parameter in the document.	None.
DocShow	String	No	Yes	Specifies whether the parameters are public in the SDK or document of API Gateway.	Valid values: PUBLIC PRIVATE
EnumValue	String	No	Yes	The hash values that can be specified when ParameterType is set to Int, Long, Float, Double, or String.	Separate multiple values with commas (,). Examples: `1,2,3,4,9` and `A,B,C,E,F`.
JsonScheme	String	No	Yes	The JSON schema that is used to validate the parameter when ParameterType is set to String.	None.
MaxLength	Integer	No	Yes	The maximum length of the parameter when ParameterType is set to String.	None.
MaxValue	Integer	No	Yes	The maximum value of the parameter when ParameterType is set to Int, Long, Float, or Double.	None.
MinLength	Integer	No	Yes	The minimum length of the parameter when ParameterType is set to String.	None.
MinValue	Integer	No	Yes	The minimum value of the parameter when ParameterType is set to Int, Long, Float, or Double.	None.
RegularExpression	String	No	Yes	The regular expression that is used to validate the parameter when ParameterType is set to String.	None.

ConstParameters syntax

"ConstParameters": [
  {
    "ConstValue": String,
    "ServiceParameterName": String,
    "Description": String,
    "Location": String
  }
]

ConstParameters properties

Property	Type	Required	Editable	Description	Constraint
ConstValue	String	Yes	Yes	The value of the constant parameter.	None.
Location	String	Yes	Yes	The location of the constant parameter.	Valid values: BODY HEAD (default)
ServiceParameterName	String	Yes	Yes	The name of the backend parameter that corresponds to the constant parameter.	None.
Description	String	No	Yes	The description of the constant parameter.	None.

FunctionComputeConfig syntax

"FunctionComputeConfig": {
 "FcRegionId": String,
 "RoleArn": String,
 "ServiceName": String,
 "FunctionName": String,
 "Qualifier": String,
 "ContentTypeValue": String,
 "ContentTypeCatagory": String,
 "FcBaseUrl": String,
 "FcType": String,
 "Method": String,
 "OnlyBusinessPath": Boolean,
 "Path": String,
 "FcVersion": String
}

FunctionComputeConfig properties

Property	Type	Required	Editable	Description	Constraint
ContentTypeCatagory	String	No	Yes	The ContentType header type used when you call the backend service over HTTP.	Valid values: DEFAULT: default header in API Gateway CUSTOM: custom header CLIENT (default): ContentType header of the client
FcVersion	String	No	No	The supported Function Compute version.	Valid values: 2.0 3.0
ContentTypeValue	String	No	Yes	The value of the ContentType header when ServiceProtocol is set to HTTP and ContentTypeCatagory is set to DEFAULT or CUSTOM.	None.
FcBaseUrl	String	No	Yes	The URL of the trigger.	The URL must start with `http://` or `https://`.
FcRegionId	String	No	Yes	The ID of the region where Function Compute resides.	None.
FcType	String	No	Yes	The function type.	Valid values: FCEvent (default) HttpTrigger
FunctionName	String	No	Yes	The name of the function that is defined in Function Compute.	None.
Method	String	No	Yes	The HTTP request method.	Valid values: GET (default) POST DELETE PUT HEAD PATCH OPTIONS ANY
OnlyBusinessPath	Boolean	No	Yes	Specifies whether to pass only the custom backend request path to the backend.	Valid values: true false
Path	String	No	Yes	The backend request path.	Parameters must be enclosed in brackets [ ]. Example: `/ getUserInfo / [userId]`.
Qualifier	String	No	Yes	The alias of the Function Compute function.	None.
RoleArn	String	No	Yes	The Alibaba Cloud Resource Name (ARN) of the Resource Access Management (RAM) role that is assigned to API Gateway to access Function Compute.	None.
ServiceName	String	No	Yes	The name of the service that is defined in Function Compute.	None.

MockHeaders syntax

"MockHeaders": [
  {
    "HeaderValue": String,
    "HeaderName": String
  }
]

MockHeaders properties

Property	Type	Required	Editable	Description	Constraint
HeaderName	String	Yes	Yes	The name of the response header.	None.
HeaderValue	String	Yes	Yes	The value of the response header.	None.

Return values

Fn::GetAtt

ApiId: the API ID.

Examples

Note

Change the values of masked parameters, such as InstanceId, based on your business requirements.

`YAML` format

ROSTemplateFormatVersion: '2015-09-01'
Description: Test ApiGateway Api
Parameters: {}
Resources:
  RamRole:
    Type: ALIYUN::RAM::Role
    Properties:
      RoleName: TestRole
      Policies:
        - PolicyName: TestPolicy
          PolicyDocument:
            Version: '1'
            Statement:
              - Action:
                  - fc:InvokeFunction
                Resource:
                  - '*'
                Effect: Allow
      AssumeRolePolicyDocument:
        Version: '1'
        Statement:
          - Action: sts:AssumeRole
            Effect: Allow
            Principal:
              Service:
                - apigateway.aliyuncs.com
  FCService:
    Type: ALIYUN::FC::Service
    Properties:
      ServiceName: TestService
      InternetAccess: true
  Function:
    Type: ALIYUN::FC::Function
    DependsOn: FCService
    Properties:
      Handler: index.handler
      Runtime: python3
      Code:
        SourceCode: "def handler(event, context):\n\treturn {'isBase64Encode': False, 'statusCode': 200, 'body': 'Hello World!', 'headers': {'Content-type': 'aplication/json'}}\n"
      FunctionName: mytest
      ServiceName:
        Fn::GetAtt:
          - FCService
          - ServiceName
      MemorySize: 128
  Group:
    Type: ALIYUN::ApiGateway::Group
    Properties:
      InstanceId: api-shared-vpc-***
      GroupName: TestGroup
  Api:
    DependsOn:
      - RamRole
      - Group
    Type: ALIYUN::ApiGateway::Api
    Properties:
      AppCodeAuthType: HEADER_QUERY
      AuthType: APP
      ServiceConfig:
        FunctionComputeConfig:
          fcRegionId:
            Ref: ALIYUN::Region
          qualifier: LATEST
          roleArn:
            Fn::GetAtt:
              - RamRole
              - Arn
          serviceName:
            Fn::GetAtt:
              - FCService
              - ServiceName
          functionName:
            Fn::GetAtt:
              - Function
              - FunctionName
        ServiceProtocol: FunctionCompute
        ContentTypeCatagory: CLIENT
      RequestConfig:
        RequestMode: MAPPING
        RequestHttpMethod: POST
        RequestProtocol: HTTP,HTTPS
        RequestPath: /test
        BodyFormat: FORM
      ResultSample: ''
      Visibility: PRIVATE
      ResultType: JSON
      ApiName: TestApi
      GroupId:
        Fn::GetAtt:
          - Group
          - GroupId
  App:
    Type: ALIYUN::ApiGateway::App
    Properties:
      Description: Test Create App
      AppName: TestApp
Outputs: {}

`JSON` format

{
  "ROSTemplateFormatVersion": "2015-09-01",
  "Description": "Test ApiGateway Api",
  "Parameters": {
  },
  "Resources": {
    "RamRole": {
      "Type": "ALIYUN::RAM::Role",
      "Properties": {
        "RoleName": "TestRole",
        "Policies": [
          {
            "PolicyName": "TestPolicy",
            "PolicyDocument": {
              "Version": "1",
              "Statement": [
                {
                  "Action": [
                    "fc:InvokeFunction"
                  ],
                  "Resource": [
                    "*"
                  ],
                  "Effect": "Allow"
                }
              ]
            }
          }
        ],
        "AssumeRolePolicyDocument": {
          "Version": "1",
          "Statement": [
            {
              "Action": "sts:AssumeRole",
              "Effect": "Allow",
              "Principal": {
                "Service": [
                  "apigateway.aliyuncs.com"
                ]
              }
            }
          ]
        }
      }
    },
    "FCService": {
      "Type": "ALIYUN::FC::Service",
      "Properties": {
        "ServiceName": "TestService",
        "InternetAccess": true
      }
    },
    "Function": {
      "Type": "ALIYUN::FC::Function",
      "DependsOn": "FCService",
      "Properties": {
        "Handler": "index.handler",
        "Runtime": "python3",
        "Code": {
          "SourceCode": "def handler(event, context):\n\treturn {'isBase64Encode': False, 'statusCode': 200, 'body': 'Hello World!', 'headers': {'Content-type': 'aplication/json'}}\n"
        },
        "FunctionName": "mytest",
        "ServiceName": {
          "Fn::GetAtt": [
            "FCService",
            "ServiceName"
          ]
        },
        "MemorySize": 128
      }
    },
    "Group": {
      "Type": "ALIYUN::ApiGateway::Group",
      "Properties": {
        "InstanceId": "api-shared-vpc-***",
        "GroupName": "TestGroup"
      }
    },
    "Api": {
      "DependsOn": [
        "RamRole",
        "Group"
      ],
      "Type": "ALIYUN::ApiGateway::Api",
      "Properties": {
        "AppCodeAuthType": "HEADER_QUERY",
        "AuthType": "APP",
        "ServiceConfig": {
          "FunctionComputeConfig": {
            "fcRegionId": {
              "Ref": "ALIYUN::Region"
            },
            "qualifier": "LATEST",
            "roleArn": {
              "Fn::GetAtt": [
                "RamRole",
                "Arn"
              ]
            },
            "serviceName": {
              "Fn::GetAtt": [
                "FCService",
                "ServiceName"
              ]
            },
            "functionName": {
              "Fn::GetAtt": [
                "Function",
                "FunctionName"
              ]
            }
          },
          "ServiceProtocol": "FunctionCompute",
          "ContentTypeCatagory": "CLIENT"
        },
        "RequestConfig": {
          "RequestMode": "MAPPING",
          "RequestHttpMethod": "POST",
          "RequestProtocol": "HTTP,HTTPS",
          "RequestPath": "/test",
          "BodyFormat": "FORM"
        },
        "ResultSample": "",
        "Visibility": "PRIVATE",
        "ResultType": "JSON",
        "ApiName": "TestApi",
        "GroupId": {
          "Fn::GetAtt": [
            "Group",
            "GroupId"
          ]
        }
      }
    },
    "App": {
      "Type": "ALIYUN::ApiGateway::App",
      "Properties": {
        "Description": "Test Create App",
        "AppName": "TestApp"
      }
    }
  },
  "Outputs": {
  }
}

Syntax

Properties

Tags syntax

Tags properties

ErrorCodeSamples syntax

ErrorCodeSamples properties

ServiceConfig syntax

ServiceConfig properties

VpcConfig syntax

VpcConfig properties

SystemParameters syntax

SystemParameters properties

ServiceParameters syntax

ServiceParameters properties

OpenIdConnectConfig syntax

OpenIdConnectConfig properties

RequestConfig syntax

RequestConfig properties

ServiceParametersMap syntax

ServiceParametersMap properties

RequestParameters syntax

RequestParameters properties

ConstParameters syntax

ConstParameters properties

FunctionComputeConfig syntax

FunctionComputeConfig properties

MockHeaders syntax

MockHeaders properties

Return values

Examples

YAML format

JSON format

`YAML` format

`JSON` format