ALIYUN::ApiGateway::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
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.
RequestConfig	Map	Yes	Yes	The configurations of API requests that are sent from the consumer to API Gateway.	For more information, see RequestConfig properties.
Visibility	String	Yes	Yes	Specifies whether the API is public.	Valid values: PUBLIC PRIVATE
ResultSample	String	Yes	Yes	The sample response from the backend service.	None.
ResultType	String	Yes	Yes	The format of the response from the backend service.	Valid values: JSON (default) TEXT BINARY XML PASSTHROUGH
ApiName	String	Yes	Yes	The name of the API.	The name must be 4 to 50 characters in length. It must start with a letter. It can contain letters, digits, and underscores (_). Note The name must be unique in an API group.
GroupId	String	Yes	No	The ID of the API group.	None.
ErrorCodeSamples	List	No	Yes	The sample error codes that are returned from the backend service.	For more information, see ErrorCodeSamples 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
ForceNonceCheck	Boolean	No	Yes	Specifies whether to forcefully check X-Ca-Nonce when the request is sent.	Valid values: true false
Tags	List	No	Yes	The tags of the API.	You can add up to 20 tags. For more information, see Tags properties.
SystemParameters	List	No	Yes	The system parameters of the API.	For more information, see SystemParameters properties.
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.
OpenIdConnectConfig	Map	No	Yes	The configurations of the third-party OpenID Connect authentication method.	For more information, see OpenIdConnectConfig properties.
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, the OpenIdConnectConfig property is required.
ServiceParametersMap	List	No	Yes	The mappings between parameters of requests sent from the consumer to API Gateway and parameters of requests sent from API Gateway to the backend service.	For more information, see ServiceParametersMap properties.
FailResultSample	String	No	Yes	The sample error response from the backend service.	None.
RequestParameters	List	No	Yes	The parameters of API requests that are sent from the consumer to API Gateway.	For more information, see RequestParameters properties.
ConstParameters	List	No	Yes	The constant parameters of the API.	For more information, see ConstParameters properties.
AppCodeAuthType	String	No	Yes	The AppCode authentication method.	This property takes effect when AuthType is set 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.
ResultBodyModel	String	No	Yes	The response of the API.	None.
AllowSignatureMethod	String	No	Yes	The signature algorithm used when AuthType is set to APP.	Valid values: HmacSHA256 (default) HmacSHA1
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
ResultDescriptions	String	No	Yes	The description of the response.	None.

Tags syntax

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

Tags properties

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

ErrorCodeSamples syntax

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

ErrorCodeSamples properties

Property	Type	Required	Editable	Description	Constraint
Message	String	Yes	Yes	The error message.	None.
Code	String	Yes	Yes	The error code.	None.
Description	String	No	Yes	The description of the error.	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
FunctionComputeConfig	Map	No	Yes	The configurations of Function Compute that is used as the backend service.	None. For more information, see FunctionComputeConfig properties.
MockStatusCode	Integer	No	Yes	The status code.	The status code is returned in a format that is compatible with HTTP/1.1.
MockHeaders	List	No	Yes	The mock response headers defined when the mock mode is enabled.	None. For more information, see MockHeaders properties.
ServiceTimeOut	Integer	No	Yes	The timeout period of the backend service.	Unit: milliseconds.
ServiceAddress	String	No	Yes	The address of the backend service.	If the complete backend service address is `http://example.com:8080/object/add?key1=value1&key2=value2`, the value of ServiceAddress is `http://example.com:8080`.
ServicePath	String	No	Yes	The path of the backend service.	If the complete backend service address is `http://example.com:8080/object/add?key1=value1&key2=value2`, the value of ServicePath is `/object/add`.
ServiceProtocol	String	No	Yes	The protocol of the backend service.	Valid values: HTTP HTTPS FunctionCompute
ServiceVpcEnable	String	No	Yes	Specifies whether to enable the Virtual Private Cloud (VPC) service.	Valid values: TRUE FALSE (default)
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
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
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.
Mock	String	No	Yes	Specifies whether to use the mock mode.	Valid values: TRUE FALSE (default)
MockResult	String	No	Yes	The result that is returned when the mock mode is used.	None.
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.
VpcId	String	Yes	Yes	The VPC ID.	None.
Port	Integer	Yes	Yes	The port number of the instance.	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 that corresponds to the system parameter.	None.
Description	String	No	Yes	The description of the system parameter.	None.
DemoValue	String	No	Yes	The sample value of the system parameter.	None.

ServiceParameters syntax

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

ServiceParameters properties

Property	Type	Required	Editable	Description	Constraint
ParameterType	String	Yes	Yes	The data type of the backend parameter.	Valid values: STRING NUMBER BOOLEAN
Location	String	Yes	Yes	The location of the backend parameter.	Valid values: BODY HEAD QUERY PATH
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 and issue a token. If you set this property to IDTOKEN, the PublicKeyId and PublicKey properties are required. BUSINESS: obtains a business API and verify a token. If you set this property to BUSINESS, the IdTokenParamName property is required.
PublicKey	String	No	Yes	The public key.	None.
PublicKeyId	String	No	Yes	The ID of the public key.	None.
IdTokenParamName	String	No	Yes	The name of the parameter that corresponds to the token.	None.

RequestConfig syntax

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

RequestConfig properties

Property	Type	Required	Editable	Description	Constraint
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 API address is `http://example.com:8080/object/add?key1=value1&key2=value2`, the value of RequestPath 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`.
RequestHttpMethod	String	Yes	Yes	The request method.	Valid values: GET (default) POST DELETE PUT HEADER TRACE PATCH OPTIONS
PostBodyDescription	String	No	Yes	The description of the request body.	None.
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 when RequestMode is set to MAPPING.

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 the ApiParameterName property 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
ParameterType	String	Yes	No	The data type of the parameter.	Valid values: String Int Long Float Double Boolean
Required	String	Yes	Yes	Specifies whether the parameter is required.	Valid values: REQUIRED OPTIONAL
ApiParameterName	String	Yes	Yes	The name of the parameter.	None.
Location	String	Yes	Yes	The location of the parameter.	Valid values: BODY HEAD QUERY PATH
RegularExpression	String	No	Yes	The regular expression that is used to validate the parameter when ParameterType is set to String.	None.
Description	String	No	Yes	The description of the parameter.	None.
DefaultValue	String	No	Yes	The default value of the parameter.	None.
MaxLength	Integer	No	Yes	The maximum length of the parameter when ParameterType is set to String.	None.
MinLength	Integer	No	Yes	The minimum 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.
MinValue	Integer	No	Yes	The minimum value of the parameter when ParameterType is set to Int, Long, Float, or Double.	None.
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.
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
DemoValue	String	No	Yes	The sample value of the parameter.	None.

ConstParameters syntax

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

ConstParameters properties

Property	Type	Required	Editable	Description	Constraint
Location	String	Yes	Yes	The location of the constant parameter.	Valid values: BODY HEAD (default)
ConstValue	String	Yes	Yes	The value of the constant parameter.	None.
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
}

FunctionComputeConfig properties

Property	Type	Required	Editable	Description	Constraint
FcRegionId	String	No	Yes	The ID of the region where Function Compute resides.	None.
RoleArn	String	No	Yes	The Alibaba Cloud Resource Name (ARN) of the 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.
FunctionName	String	No	Yes	The name of the function that is defined in Function Compute.	None.
Qualifier	String	No	Yes	The alias of the service that is defined in Function Compute.	None.
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
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://`.
FcType	String	No	Yes	The type of the function.	Valid values: FCEvent (default) HttpTrigger
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]`.

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

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-001
      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-001",
        "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": {
  }
}

For more examples, visit Api.json and Api.yml. In the examples, the following resource types are used: ALIYUN::ApiGateway::Api, ALIYUN::ApiGateway::App, ALIYUN::ApiGateway::Authorization, ALIYUN::ApiGateway::Deployment, ALIYUN::ApiGateway::Signature, ALIYUN::ApiGateway::SignatureBinding, ALIYUN::ApiGateway::TrafficControl, and ALIYUN::ApiGateway::TrafficControlBinding.