ALIYUN::ApiGateway::Api - Create an API Gateway API - Resource Orchestration Service

ALIYUN::ApiGateway::Api creates an API in API Gateway.

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 name	Type	Required	Update allowed	Description	Constraints
ApiName	String	Yes	Yes	The name of the API.	The value must be 4 to 50 characters long. It must start with an English letter or a Chinese character and can contain only English letters, Chinese characters, digits, and underscores (_). Note API names must be unique within an API group.
GroupId	String	Yes	No	The ID of the API group.	None
RequestConfig	Map	Yes	Yes	Configuration for API requests sent from consumers to API Gateway.	RequestConfig properties.
ResultSample	String	No	Yes	Sample backend service response.	None
ResultType	String	No	Yes	The format of the backend service response.	Valid values: JSON (default) TEXT BINARY XML PASSTHROUGH
ServiceConfig	Map	Yes	Yes	Configuration for API requests sent from API Gateway to the backend service.	ServiceConfig properties.
Visibility	String	Yes	Yes	Whether the API is public.	Valid values: Public PRIVATE: The resource is not public.
AllowSignatureMethod	String	No	Yes	Required when AuthType is APP. Sets the signature algorithm.	Valid values: HmacSHA256 (default) HmacSHA1
AppCodeAuthType	String	No	Yes	The AppCode authentication type.	Valid only ifyou set AuthType to APP. Valid values: DEFAULT (default): The setting of the API group is used. DISABLE: The operation is not allowed. HEADER: AppCode authentication is allowed only for requests that include the AppCode header. HEADER_QUERY: AppCode authentication is allowed for requests that include the AppCode header or the AppCode query parameter.
AuthType	String	No	Yes	The security authentication type of the API.	Valid values: APP: Only authorized apps can call the API. ANONYMOUS: Anonymous calls are allowed. API Gateway does not perform identity authentication on the caller and cannot set throttling policies for the caller. If the API group to which the API belongs is to be listed on Alibaba Cloud Marketplace, move the API to another group, set the API to private, or use Alibaba Cloud app authentication. APPOPENID: OpenID Connect is used for third-party identity authentication, and only authorized apps can call the API. If you set AuthType to this value, you must specify OpenIdConnectConfig.
ConstParameters	List	No	Yes	The constant parameters of the API.	ConstParameters properties.
Description	String	No	Yes	API description.	The description can be up to 180 characters in length.
DisableInternet	Boolean	No	Yes	Whether to disable calls over the public network.	Valid values: true: Prohibited. false: The operation is allowed.
ErrorCodeSamples	List	No	Yes	Sample error codes returned by the backend service.	ErrorCodeSamples properties.
FailResultSample	String	No	Yes	Sample failed-request response from the backend service.	None
ForceNonceCheck	Boolean	No	Yes	Whether to forcibly check X-Ca-Nonce.	Valid values: true: A check is forced. false: A mandatory check is not performed.
OpenIdConnectConfig	Map	No	Yes	OpenID Connect authentication configuration.	OpenIdConnectConfig properties.
RequestParameters	List	No	Yes	Parameters for API requests sent from consumers to API Gateway.	RequestParameters properties.
ResultBodyModel	String	No	Yes	The return result of the API.	None
ResultDescriptions	String	No	Yes	Result description.	None
ServiceParameters	List	No	Yes	Parameters for API requests sent from API Gateway to the backend service.	ServiceParameters properties.
ServiceParametersMap	List	No	Yes	Mappings between consumer-to-gateway and gateway-to-backend request parameters.	ServiceParametersMap properties.
SystemParameters	List	No	Yes	The system parameters of the API.	SystemParameters properties.
Tags	List	No	Yes	The tags.	You can add up to 20 tags. Tags properties.
WebSocketApiType	String	No	Yes	The type of the bidirectional communication API.	Valid values: COMMON: a common API. REGISTER: a registration API. UNREGISTER: an unregistration API. NOTIFY: a downlink notification.

Tags syntax

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

Tags properties

Property name	Type	Required	Update allowed	Description	Constraints
Key	String	Yes	No	The tag key.	The tag key can be 1 to 128 characters in length. It cannot start with `aliyun` or `acs:` and cannot contain `http://` or `https://`.
Value	String	No	No	The tag value.	The tag value can be 0 to 128 characters in length. It cannot start with `aliyun` or `acs:` and cannot contain `http://` or `https://`.

ErrorCodeSamples syntax

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

ErrorCodeSamples properties

Property name	Type	Required	Update allowed	Description	Constraints
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 name	Type	Required	Update allowed	Description	Constraints
ContentTypeCatagory	String	No	Yes	The policy for setting the value of the Content-Type header when you call the backend HTTP service.	Valid values: DEFAULT: The default value of API Gateway is used. CUSTOM: A custom value is used. CLIENT (default): The Content-Type header of the client request is used.
ContentTypeValue	String	No	Yes	The value of the Content-Type header when the backend service is an HTTP service and ContentTypeCatagory is set to DEFAULT or CUSTOM.	None
FunctionComputeConfig	Map	No	Yes	The backend service is Function Compute.	None FunctionComputeConfig properties.
Mock	String	No	Yes	Whether to enable mock mode.	Valid values: TRUE: enables mock mode. FALSE (default): does not enable mock mode.
MockHeaders	List	No	Yes	The custom mock response headers. This parameter is valid only when mock mode is enabled.	None MockHeaders properties.
MockResult	String	No	Yes	The result returned in mock mode.	None
MockStatusCode	Integer	No	Yes	The status code.	The status code must be compatible with HTTP 1.1 response status codes.
ServiceAddress	String	No	Yes	The endpoint of the backend service.	For example, if the full address of the backend service is `http://example.com:8080/object/add?key1=value1&key2=value2`, the endpoint 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.	For example, if the full address 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	Whether to use a VPC.	Valid values: TRUE: Enabled. FALSE (default): Disabled.
VpcConfig	Map	No	Yes	The configurations of the VPC channel.	VpcConfig properties.

VpcConfig syntax

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

VpcConfig properties

Property name	Type	Required	Update allowed	Description	Constraints
InstanceId	String	Yes	Yes	The ID of the instance in the VPC.	Only ECS and SLB instances are supported.
Port	Integer	Yes	Yes	The port number of the instance.	None
VpcId	String	Yes	Yes	The ID of the VPC.	None

SystemParameters syntax

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

SystemParameters properties

Property name	Type	Required	Update allowed	Description	Constraints
Location	String	Yes	Yes	The location of the 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	Example.	None
Description	String	No	Yes	Parameter description.	None

ServiceParameters syntax

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

ServiceParameters properties

Property name	Type	Required	Update allowed	Description	Constraints
Location	String	Yes	Yes	The location of the parameter.	Valid values: BODY HEAD QUERY PATH
ParameterType	String	Yes	Yes	The data type of the backend parameter.	Valid values: STRING: a string. NUMBER: a number. BOOLEAN: a Boolean value.
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 name	Type	Required	Update allowed	Description	Constraints
OpenIdApiType	String	Yes	Yes	The OpenID Connect mode.	Valid values: IDTOKEN: The API is an authorization API that is used to obtain a token. If you set OpenIdApiType to this value, you must specify PublicKeyId and PublicKey. BUSINESS: Obtains the business API and performs token authentication. This option requires you to specify the IdTokenParamName parameter.
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 name	Type	Required	Update allowed	Description	Constraints
RequestHttpMethod	String	Yes	Yes	The request method.	Valid values: GET (default) POST DELETE PUT HEADER TRACE PATCH OPTIONS
RequestMode	String	Yes	Yes	The request mode.	Valid values: MAPPING (default): Parameters are mapped. PASSTHROUGH: Parameters are passed through.
RequestPath	String	Yes	Yes	The URI of the request.	For example, if the full URI of the API is `http://example.com:8080/object/add?key1=value1&key2=value2`, the URI of the request is `/object/add`.
RequestProtocol	String	Yes	Yes	The protocol types supported by the API.	Valid values: HTTP HTTPS Separate multiple protocols with commas (,), for example, `HTTP,HTTPS`.
BodyFormat	String	No	Yes	For POST, PUT, or PATCH requests, specifies how data is passed to the server.	Valid values: FORM: The data is passed as a form. STREAM: The data is passed as a byte stream. Valid only ifRequestMode is set to MAPPING.
PostBodyDescription	String	No	Yes	Request body description.	None

ServiceParametersMap syntax

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

ServiceParametersMap properties

Property name	Type	Required	Update allowed	Description	Constraints
RequestParameterName	String	Yes	Yes	The name of the frontend parameter.	The value of this parameter must exist in RequestParameters. Must match 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 name	Type	Required	Update allowed	Description	Constraints
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
ParameterType	String	Yes	No	The type of the parameter.	Valid values: String: A sequence of characters. Int: an integer. Long: a long integer. Float: a single-precision floating-point number. Double: a double-precision floating-point number. Boolean: a Boolean value.
Required	String	Yes	Yes	Whether the parameter is required.	Valid values: REQUIRED: The parameter is required. OPTIONAL: The parameter is optional.
DefaultValue	String	No	Yes	The default value.	None
DemoValue	String	No	Yes	Sample value.	None
Description	String	No	Yes	Parameter description.	None
DocOrder	Integer	No	Yes	The order within the document.	None
DocShow	String	No	Yes	Whether the SDK or documents generated by API Gateway are visible.	Valid values: PUBLIC PRIVATE
EnumValue	String	No	Yes	The valid values of the parameter when ParameterType is set to Int, Long, Float, Double, or String.	Separate multiple values with commas (,), for example, `1,2,3,4,9` or `A,B,C,E,F`.
JsonScheme	String	No	Yes	If ParameterType is set to String, the parameter is verified based on the JSON schema.	None
MaxLength	Integer	No	Yes	The maximum length of the parameter. Valid only ifParameterType is set to String.	None
MaxValue	Integer	No	Yes	The maximum value of the parameter. Valid only ifParameterType is set to Int, Long, Float, or Double.	None
MinLength	Integer	No	Yes	The minimum length of the parameter. Valid only ifParameterType is set to String.	None
MinValue	Integer	No	Yes	The minimum value of the parameter. Valid only ifParameterType is set to Int, Long, Float, or Double.	None
RegularExpression	String	No	Yes	If ParameterType is set to String, the parameter is verified based on the regular expression.	None

ConstParameters syntax

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

ConstParameters properties

Property name	Type	Required	Update allowed	Description	Constraints
ConstValue	String	Yes	Yes	The value of the parameter.	None
Location	String	Yes	Yes	The location of the parameter.	Valid values: BODY HEAD (default)
ServiceParameterName	String	Yes	Yes	The name of the backend parameter.	None
Description	String	No	Yes	Parameter description.	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 name	Type	Required	Update allowed	Description	Constraints
ContentTypeCatagory	String	No	Yes	The policy for setting the value of the Content-Type header when you call the backend HTTP service.	Valid values: DEFAULT: The default value of API Gateway is used. CUSTOM: A custom value is used. CLIENT (default): The Content-Type header of the client request is used.
FcVersion	String	No	No	The version of Function Compute.	Valid values: 2.0 3.0
ContentTypeValue	String	No	Yes	The value of the Content-Type header when you call the backend HTTP service and ContentTypeCatagory is set to DEFAULT or CUSTOM.	None
FcBaseUrl	String	No	Yes	The endpoint of the trigger.	The endpoint must start with `http://` or `https://`.
FcRegionId	String	No	Yes	The ID of the region where Function Compute is deployed.	None
FcType	String	No	Yes	The type of the function.	Valid values: FCEvent (default). HttpTrigger.
FunctionName	String	No	Yes	The name of the function 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	Whether to pass only the custom backend request path to the backend service.	Valid values: true false
Path	String	No	Yes	The path of the backend request.	The parameter must be enclosed in brackets ([]), for example, `/getUserInfo/[userId]`.
Qualifier	String	No	Yes	The alias of the function in Function Compute.	None
RoleArn	String	No	Yes	The ARN of the RAM role that is assumed by API Gateway to access Function Compute.	None
ServiceName	String	No	Yes	The name of the service in Function Compute.	None

MockHeaders syntax

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

MockHeaders properties

Property name	Type	Required	Update allowed	Description	Constraints
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 ID of the API.
ARN stands for Alibaba Cloud Resource Name.

Examples

Note

Change the parameter values in the following examples based on your requirements. For example, you must change the value of InstanceId.

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