DescribeApi - API Gateway - Alibaba Cloud Documentation Center

Queries the definition of an API.

Operation description

This operation is intended for API providers.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

Debug

Authorization information

There is currently no authorization information disclosed in the API.

Request parameters

Parameter	Type	Required	Description	Example
GroupId	string	No	The ID of the API group.	123
ApiId	string	Yes	The ID of the API.	8afff6c8c4c6447abb035812e4d66b65

Response parameters

Parameter	Type	Description	Example
	object
ApiId	string	The ID of the API.	8afff6c8c4c6447abb035812e4d66b65
ResultType	string	The format of the response from the backend service. Valid values: JSON, TEXT, BINARY, XML, and HTML.	JSON
WebSocketApiType	string	The type of the two-way communication API. COMMON: common API REGISTER: registered API UNREGISTER: unregistered API NOTIFY: downstream notification API	COMMON
DisableInternet	boolean	Specifies whether to limit API calls to within the VPC. Valid values: true: Only API calls from the VPC are supported. false: API calls from the VPC and Internet are both supported.	false
ResultBodyModel	string	The returned description of the API.	{}
ResultSample	string	The sample response from the backend service.	200
AppCodeAuthType	string	If AuthType is set to APP, the valid values are: DEFAULT: The default value that is used if no other values are passed. This value means that the setting of the group is used. DISABLE: The authentication is disabled. HEADER: AppCode can be placed in the Header parameter for authentication. HEADER_QUERY: AppCode can be placed in the Header or Query parameter for authentication.	HEADER
AllowSignatureMethod	string	If AuthType is set to APP, this value must be passed to specify the signature algorithm. If you do not specify a value, HmacSHA256 is used by default. Valid values: HmacSHA256 HmacSHA1,HmacSHA256	HmacSHA256
RegionId	string	The region ID of the API.	cn-qingdao
ForceNonceCheck	boolean	Specifies whether to carry the header : X-Ca-Nonce when calling an API. This is the unique identifier of the request and is generally identified by UUID. After receiving this parameter, API Gateway verifies the validity of this parameter. The same value can be used only once within 15 minutes. This helps prevent reply attacks. Valid values: true: This field is forcibly checked when an API is requested to prevent replay attacks. false: This field is not checked.	true
Visibility	string	Specifies whether to make the API public. Valid values: PUBLIC: Make the API public. If you set this parameter to PUBLIC, this API is displayed on the APIs page for all users after the API is published to the production environment. PRIVATE: Make the API private. Private APIs are not displayed in the Alibaba Cloud Marketplace after the API group to which they belong is made available.	PUBLIC
FailResultSample	string	The sample error response from the backend service.	400
AuthType	string	The security authentication method of the API. Valid values: APP: Only authorized applications can call the API. ANONYMOUS: The API can be anonymously called. In this mode, you must take note of the following rules: All users who have obtained the API service information can call this API. API Gateway does not authenticate callers and cannot set user-specific throttling policies. If you make this API public, set API-specific throttling policies. We recommend that you do not make the API whose security authentication method is ANONYMOUS available in Alibaba Cloud Marketplace because API Gateway cannot meter calls on the caller or limit the number of calls on the API. If you want to make the API group to which the API belongs available in Alibaba Cloud Marketplace, we recommend that you move the API to another group, set its type to PRIVATE, or set its security authentication method to APP. APPOPENID: The OpenID Connect account authentication method is used. Only applications authorized by OpenID Connect can call the API. If this method is selected, the OpenIdConnectConfig parameter is required.	APP
ModifiedTime	string	The last modification time of the API.	2016-07-28T13:13:12Z
RequestId	string	The ID of the request.	D0FF585F-7966-40CF-BC60-75DB070B23D5<
Description	string	The description of the API.	Api description
GroupName	string	The name of the API group.	ApiTest
GroupId	string	The ID of the API group.	08ae4aa0f95e4321849ee57f4e0b3077
Mock	string	Specifies whether to enable the Mock mode. Valid values: OPEN: The Mock mode is enabled. CLOSED: The Mock mode is not enabled.	CLOSED
MockResult	string	The result returned for service mocking.	test result
CreatedTime	string	The creation time of the API.	2016-07-28T09:50:43Z
ApiName	string	The name of the API, which is unique in the group.	ApiName
BackendEnable	boolean	Specifies whether to enable backend services.	true
BackendConfig	object	Backend configurations
BackendId	string	The ID of the backend service.	0038e00c3dca44fcba3a94015d8f5bbf
BackendType	string	Backend service type	HTTP
BackendName	string	The name of the backend service.	testoss
RequestConfig	object	The configuration items of API requests sent by the consumer to API Gateway.
BodyModel	string	The body model.	https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab
RequestPath	string	The API request path. If the complete API URL is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, the API request path is `/object/add` .	/api/billing/test/[type]
RequestHttpMethod	string	The HTTP method used to make the request. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.	POST
BodyFormat	string	This parameter takes effect only when the RequestMode parameter is set to MAPPING.******** The server data transmission method used for POST and PUT requests. Valid values: FORM and STREAM. FORM indicates that data in key-value pairs is transmitted as forms. STREAM indicates that data is transmitted as byte streams.	STREAM
RequestMode	string	The request mode. Valid values: MAPPING and PASSTHROUGH.	MAPPING
PostBodyDescription	string	The description of the request body.	fwefwef
RequestProtocol	string	The protocol type supported by the API. Valid values: HTTP and HTTPS. Separate multiple values with commas (,), such as "HTTP,HTTPS".	HTTP
EscapePathParam	boolean	Whether to escape the Path parameter, if true, the [param] on the Path will be treated as a regular character.	true
ServiceConfig	object	The configuration items of API requests that API Gateway sends to the backend service.
AoneAppName	string	The application name in AONE.	ib-blank
MockStatusCode	integer	The status code returned for service mocking.	200
ContentTypeValue	string	The value of the ContentType header when the ServiceProtocol parameter is set to HTTP and the ContentTypeCatagory parameter is set to DEFAULT or CUSTOM.	application/x-www-form-urlencoded; charset=UTF-8
ServiceProtocol	string	The protocol used by the backend service. Valid values: HTTP and HTTPS.	HTTP
ServicePath	string	The path used to call the back-end service. If the complete back-end service path is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, ServicePath is /object/add.``	/object/add
ContentTypeCatagory	string	The ContentType header type used when you call the backend service over HTTP. DEFAULT: the default header type in API Gateway CUSTOM: a custom header type CLIENT: the ContentType header type of the client	CUSTOM
ServiceAddress	string	The URL used to call the back-end service. If the complete back-end service URL is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, the value of ServiceAddress is http://api.a.com:8080.``	http://api.a.com:8080
Mock	string	Specifies whether to enable the Mock mode. Valid values: TRUE: The Mock mode is enabled. FALSE: The Mock mode is not enabled.	TRUE
ServiceVpcEnable	string	Specifies whether to enable the VPC channel. Valid values: TRUE: The VPC channel is enabled. You must create the corresponding VPC access authorization before you can enable a VPC channel. FALSE: The VPC channel is not enabled.	TRUE
MockResult	string	The result returned when the Mock mode is enabled.	test result
ServiceHttpMethod	string	The HTTP method used to call a backend service. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.	POST
ServiceTimeout	integer	The timeout period of the backend service. Unit: milliseconds.	1000
MockHeaders	array<object>	The simulated headers.
MockHeader	object
HeaderValue	string	The value of the HTTP header.	86400
HeaderName	string	The HTTP header.	Content-Length
VpcConfig	object	Configuration items related to VPC channels
VpcId	string	The ID of the VPC.	vpc-2zeafsc3fygk1***
VpcScheme	string	The VPC protocol.	HTTP
InstanceId	string	The ID of the ECS or SLB instance in the VPC.	i-bp1h497hkijewv2***
Port	integer	The port number that corresponds to the instance.	8080
Name	string	The name of the VPC access authorization.	glmall-app-test
FunctionComputeConfig	object	Backend configuration items when the backend service is Function Compute
FcType	string	The type of the Function Compute instance.	HttpTrigger
RoleArn	string	The Alibaba Cloud Resource Name (ARN) of the RAM role to be assumed by API Gateway to access Function Compute.	acs:ram::111***:role/aliyunserviceroleforsas
Method	string	The request method.	GET
FcBaseUrl	string	The root path of Function Compute.	https://1227**64334133.ap-southeast-1-intal.fc.aliyuncs.com/201*-15/proxy/test**ice.LATEST/testHttp/
ContentTypeValue	string	The value of the ContentType header when the ContentTypeCatagory parameter is set to DEFAULT or CUSTOM.	application/x-www-form-urlencoded; charset=UTF-8
RegionId	string	The region where the Function Compute instance is located.	cn-qingdao
OnlyBusinessPath	boolean	The backend only receives the service path.	false
FunctionName	string	The function name defined in Function Compute.	edge_function
ContentTypeCatagory	string	The ContentType header type used when you call the backend service over HTTP. DEFAULT: the default header type in API Gateway CUSTOM: a custom header type CLIENT: the ContentType header type of the client	DEFAULT
Path	string	The API request path.	/api/offline/cacheData
ServiceName	string	The service name defined in Function Compute.	fcservicename
Qualifier	string	The alias of the function.	2
OssConfig	object	The information returned when the backend service is Object Storage Service (OSS).
Key	string	The stored object or folder path.	/folder/test.json
Action	string	The operation options on OSS. Valid values: GetObject PostObject DeleteObject PutObject HeadObject GetObjectMeta AppendObject	GetObject
OssRegionId	string	The ID of the region where the OSS instance is located.	cn-hangzhou
BucketName	string	The OSS bucket.	cbg-db
EventBridgeConfig	object	Configuration items of EventBridge
EventBus	string	The event bus.	testBus
EventSource	string	The event source.	baas_driver
EventBridgeRegionId	string	The ID of the region where the EventBridge instance is located.	cn-beijing
RoleArn	string	The Arn that is authorized by a RAM user to EventBridge.	acs:ram::1933122015759***:role/adminoidcaliyun
OpenIdConnectConfig	object	Configuration items of the third-party OpenID Connect authentication method
OpenIdApiType	string	The OpenID Connect mode. Valid values: IDTOKEN: indicates the APIs that are called by clients to obtain tokens. If you specify this value, the PublicKeyId parameter and the PublicKey parameter are required. BUSINESS: indicates business APIs. Tokens are used to call the business APIs. If you specify this value, the IdTokenParamName parameter is required.	IDTOKEN
IdTokenParamName	string	The name of the parameter that corresponds to the token.	xxx
PublicKeyId	string	The ID of the public key.	88483727556929326703309904351185815489
PublicKey	string	The public key.	EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92
ErrorCodeSamples	array<object>	The sample error codes returned by the backend service.
ErrorCodeSample	object
Code	string	The returned error code.	400
Model	string	The model.	[\"*\"]
Message	string	The returned error message.	Missing the parameter UserId
Description	string	The error description.	The UserId parameter is missing from the request.
SystemParameters	array<object>	System parameters sent by API Gateway to the backend service
SystemParameter	object
DemoValue	string	The example value.	192.168.1.1
Description	string	The parameter description.	Client IP Address
ParameterName	string	The system parameter. Valid values: CaClientIp, CaDomain, CaRequestHandleTime, CaAppId, CaRequestId, CaHttpSchema, and CaProxy.	CaClientIp
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The mapped parameter name in the backend service.	clientIp
CustomSystemParameters	array<object>	Custom system parameters
CustomSystemParameter	object
DemoValue	string	The example value.	192.168.1.1
Description	string	The parameter description.	Client IP Address
ParameterName	string	The name of the system parameter. Valid values: CaClientIp, CaDomain, CaRequestHandleTime, CaAppId, CaRequestId, CaHttpSchema, and CaProxy.	CaClientIp
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The mapped parameter name in the backend service.	clientIp
ConstantParameters	array<object>	System parameters sent by API Gateway to the backend service
ConstantParameter	object
Description	string	The parameter description.	constance
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The mapped parameter name in the backend service.	constance
ConstantValue	string	The constant parameter value.	constance
RequestParameters	array<object>	The parameters of API requests sent by the consumer to API Gateway.
RequestParameter	object
JsonScheme	string	The JSON Schema used for JSON validation when ParameterType is set to String.	JSON
MaxValue	long	The maximum parameter value when ParameterType is set to Int, Long, Float, or Double.	123456
ArrayItemsType	string	The type of the array element.	String
MinValue	long	The minimum parameter value when ParameterType is set to Int, Long, Float, or Double.	123456
DocShow	string	Indicates whether the document is public. Valid values: PUBLIC and PRIVATE.	PUBLIC
MaxLength	long	The maximum parameter length when ParameterType is set to String.	123456
DefaultValue	string	The default value.	20
ApiParameterName	string	The parameter name.	age
EnumValue	string	The hash values that are supported when ParameterType is set to Int, Long, Float, Double, or String. Separate values with commas (,). Examples: 1,2,3,4,9 and A,B,C,E,F.	boy,girl
DemoValue	string	The example value.	20
Required	string	Indicates whether the parameter is required. Valid values: REQUIRED and OPTIONAL.	OPTIONAL
Description	string	The parameter description.	Age
ParameterType	string	The data type of the parameter. Valid values: String, Int, Long, Float, Double, and Boolean.	String
RegularExpression	string	The regular expression that is used for parameter validation when ParameterType is set to String.	xxx
MinLength	long	The minimum parameter length when ParameterType is set to String.	123456
DocOrder	integer	The order in which the parameter is sorted in the document.	0
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameters	array<object>	The parameters of API requests sent by API Gateway to the backend service.
ServiceParameter	object
Location	string	The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ParameterType	string	The data type of the parameter. Valid values: STRING, NUMBER, and BOOLEAN.	String
ServiceParameterName	string	The mapped parameter name in the backend service.	clientIp
ServiceParametersMap	array<object>	The mappings between parameters of requests sent by the consumer to API Gateway and parameters of requests sent by API Gateway to the backend service.
ServiceParameterMap	object
RequestParameterName	string	The corresponding frontend parameter name. The value must be contained in RequestParametersObject and match RequestParam.ApiParameterName.	sex
ServiceParameterName	string	The mapped parameter name in the backend service.	sex
DeployedInfos	array<object>	The API publishing status.
DeployedInfo	object
StageName	string	The environment to which the API is published. Valid values: RELEASE and TEST.	RELEASE
EffectiveVersion	string	The effective version.	xxx
DeployedStatus	string	The deployment status. Valid values: DEPLOYED and NONDEPLOYED.	DEPLOYED
TagList	array<object>	Tag List.
Tag	object
TagKey	string	Label key.	APP
TagValue	string	Label value.	value3

Examples

Sample success responses

JSONformat

{
  "ApiId": "8afff6c8c4c6447abb035812e4d66b65",
  "ResultType": "JSON",
  "WebSocketApiType": "COMMON",
  "DisableInternet": false,
  "ResultBodyModel": "{}",
  "ResultSample": "200",
  "AppCodeAuthType": "HEADER",
  "AllowSignatureMethod": "HmacSHA256",
  "RegionId": "cn-qingdao",
  "ForceNonceCheck": true,
  "Visibility": "PUBLIC",
  "FailResultSample": "400",
  "AuthType": "APP",
  "ModifiedTime": "2016-07-28T13:13:12Z",
  "RequestId": "D0FF585F-7966-40CF-BC60-75DB070B23D5<",
  "Description": "Api description",
  "GroupName": "ApiTest",
  "GroupId": "08ae4aa0f95e4321849ee57f4e0b3077",
  "Mock": "CLOSED",
  "MockResult": "test result",
  "CreatedTime": "2016-07-28T09:50:43Z",
  "ApiName": "ApiName",
  "BackendEnable": true,
  "BackendConfig": {
    "BackendId": "0038e00c3dca44fcba3a94015d8f5bbf",
    "BackendType": "HTTP",
    "BackendName": "testoss"
  },
  "RequestConfig": {
    "BodyModel": "https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab",
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP",
    "EscapePathParam": true
  },
  "ServiceConfig": {
    "AoneAppName": "ib-blank",
    "MockStatusCode": 200,
    "ContentTypeValue": "application/x-www-form-urlencoded; charset=UTF-8",
    "ServiceProtocol": "HTTP",
    "ServicePath": "/object/add",
    "ContentTypeCatagory": "CUSTOM",
    "ServiceAddress": "http://api.a.com:8080",
    "Mock": "TRUE",
    "ServiceVpcEnable": "TRUE",
    "MockResult": "test result",
    "ServiceHttpMethod": "POST",
    "ServiceTimeout": 1000,
    "MockHeaders": {
      "MockHeader": [
        {
          "HeaderValue": "86400",
          "HeaderName": "Content-Length"
        }
      ]
    },
    "VpcConfig": {
      "VpcId": "vpc-2zeafsc3fygk1***",
      "VpcScheme": "HTTP",
      "InstanceId": "i-bp1h497hkijewv2***",
      "Port": 8080,
      "Name": "glmall-app-test"
    },
    "FunctionComputeConfig": {
      "FcType": "HttpTrigger",
      "RoleArn": "acs:ram::111***:role/aliyunserviceroleforsas",
      "Method": "GET",
      "FcBaseUrl": "https://1227****64334133.ap-southeast-1-int***al.fc.aliyuncs.com/201****-15/proxy/test****ice.LATEST/testHttp/",
      "ContentTypeValue": "application/x-www-form-urlencoded; charset=UTF-8",
      "RegionId": "cn-qingdao",
      "OnlyBusinessPath": false,
      "FunctionName": "edge_function",
      "ContentTypeCatagory": "DEFAULT",
      "Path": "/api/offline/cacheData",
      "ServiceName": "fcservicename",
      "Qualifier": "2"
    },
    "OssConfig": {
      "Key": "/folder/test.json",
      "Action": "GetObject",
      "OssRegionId": "cn-hangzhou",
      "BucketName": "cbg-db"
    },
    "EventBridgeConfig": {
      "EventBus": "testBus",
      "EventSource": "baas_driver",
      "EventBridgeRegionId": "cn-beijing",
      "RoleArn": "acs:ram::1933122015759***:role/adminoidcaliyun"
    }
  },
  "OpenIdConnectConfig": {
    "OpenIdApiType": "IDTOKEN",
    "IdTokenParamName": "xxx",
    "PublicKeyId": "88483727556929326703309904351185815489",
    "PublicKey": "EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92"
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "400",
        "Model": "[\\\"*\\\"]",
        "Message": "Missing the parameter UserId",
        "Description": "The UserId parameter is missing from the request.\n"
      }
    ]
  },
  "SystemParameters": {
    "SystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "Client IP Address\n",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "CustomSystemParameters": {
    "CustomSystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "Client IP Address\n",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ConstantParameters": {
    "ConstantParameter": [
      {
        "Description": "constance",
        "Location": "HEAD",
        "ServiceParameterName": "constance",
        "ConstantValue": "constance"
      }
    ]
  },
  "RequestParameters": {
    "RequestParameter": [
      {
        "JsonScheme": "JSON",
        "MaxValue": 123456,
        "ArrayItemsType": "String",
        "MinValue": 123456,
        "DocShow": "PUBLIC",
        "MaxLength": 123456,
        "DefaultValue": "20",
        "ApiParameterName": "age",
        "EnumValue": "boy,girl",
        "DemoValue": "20",
        "Required": "OPTIONAL",
        "Description": "Age\n",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 123456,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  },
  "ServiceParameters": {
    "ServiceParameter": [
      {
        "Location": "HEAD",
        "ParameterType": "String",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ServiceParametersMap": {
    "ServiceParameterMap": [
      {
        "RequestParameterName": "sex",
        "ServiceParameterName": "sex"
      }
    ]
  },
  "DeployedInfos": {
    "DeployedInfo": [
      {
        "StageName": "RELEASE",
        "EffectiveVersion": "xxx",
        "DeployedStatus": "DEPLOYED"
      }
    ]
  },
  "TagList": {
    "Tag": [
      {
        "TagKey": "APP",
        "TagValue": "value3"
      }
    ]
  }
}

Error codes

For a list of error codes, visit the Service error codes.

Change history

Change time	Summary of changes	Operation
2024-05-27	The response structure of the API has changed	View Change Details
2024-03-14	The response structure of the API has changed	View Change Details
2023-07-11	The response structure of the API has changed	View Change Details