DescribeApi - API Gateway - Alibaba Cloud Documentation Center

Retrieves the definition of a specified API.

Operation description

This operation is available for open APIs.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

apigateway:DescribeApi

get

*ApiGroup

acs:apigateway:{#regionId}:{#accountId}:apigroup/{#GroupId}

None

Request parameters

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

Response elements

Element	Type	Description	Example
	object
ApiId	string	The ID of the API.	8afff6c8c4c6447abb035812e4d66b65
ResultType	string	The format of the response returned by the backend service. Valid values: JSON, TEXT, BINARY, XML, and HTML.	JSON
WebSocketApiType	string	The type of the bidirectional API: COMMON: a common API REGISTER: a registration API UNREGISTER: an unregistration API NOTIFY: a downstream notification	COMMON
DisableInternet	boolean	Specifies whether the API can be called only from an internal network. Valid values: true: The API can be called only from an internal network. false: The API can be called from the internet and internal networks.	false
ResultBodyModel	string	The returned result of the API.	{}
ResultSample	string	A sample response from the backend service.	200
AppCodeAuthType	string	If AuthType is set to APP, this parameter is available. Valid values: DEFAULT: This is the default value. It inherits the settings of the API group. DISABLE: AppCode authentication is not allowed. HEADER: AppCode authentication is allowed only for requests that carry the AppCode in the header. HEADER_QUERY: AppCode authentication is allowed for requests that carry the AppCode in the header or query parameters.	HEADER
AllowSignatureMethod	string	If AuthType is set to APP, you must specify this parameter to specify the signature algorithm. If you do not specify this parameter, HmacSHA256 is used by default. Valid values: HmacSHA256 HmacSHA1,HmacSHA256	HmacSHA256
RegionId	string	The ID of the region where the API resides.	cn-qingdao
ForceNonceCheck	boolean	Specifies whether the X-Ca-Nonce header must be included in API calls. This header is a unique identifier for the request, typically a UUID. API Gateway verifies this parameter to prevent replay attacks. The same value can be used only once within 15 minutes. Valid values: true: This field is forcibly checked to prevent replay attacks. false: This field is not checked.	true
Visibility	string	Specifies whether the API is public. Valid values: PUBLIC: The API is public. If you select this option, the API is displayed on the Discover APIs page in the console for all users. PRIVATE: The API is private. If the API group to which the API belongs is listed on Alibaba Cloud Marketplace, the API is not listed.	PUBLIC
FailResultSample	string	A sample failed response from the backend service.	400
AuthType	string	The security authentication type of the API. Valid values: APP: Only authorized applications can call the API. ANONYMOUS: Anonymous calls are allowed. Note: Anyone who obtains the API service information can call this API. API Gateway does not perform identity authentication on the caller and cannot apply user-specific throttling. If you make this API public, configure throttling for the API. Do not list ANONYMOUS APIs on the Alibaba Cloud Marketplace. API Gateway cannot perform metering or limit the number of calls for individual callers. If the API group is to be listed on the Alibaba Cloud Marketplace, move the API to another group, set its type to private, or select the Alibaba Cloud APP authentication method. APPOPENID: OpenID Connect and APP authentication are used. Only authorized applications can call the API. If you set this parameter to this value, you must also set OpenIdConnectConfig.	APP
ModifiedTime	string	The time when the API was last modified.	2016-07-28T13:13:12Z
RequestId	string	The request ID.	D0FF585F-7966-40CF-BC60-75DB070B23D5<
Description	string	The description of the API.	Api description
GroupName	string	The name of the group to which the API belongs.	ApiTest
GroupId	string	The ID of the group to which the API belongs.	08ae4aa0f95e4321849ee57f4e0b3077
Mock	string	Specifies whether to enable mock mode. Valid values: OPEN: Mock mode is enabled. CLOSED: Mock mode is not enabled.	CLOSED
MockResult	string	The mock response.	test result
CreatedTime	string	The time when the API was created.	2016-07-28T09:50:43Z
ApiName	string	The name of the API. The name must be unique within the API group.	ApiName
BackendEnable	boolean	Specifies whether to enable the backend service.	true
BackendConfig	object	The backend configurations.
BackendId	string	The ID of the backend service.	0038e00c3dca44fcba3a94015d8f5bbf
BackendType	string	The type of the backend service.	HTTP
BackendName	string	The name of the backend service.	testoss
RequestConfig	object	The configurations for API requests that are sent from a consumer to API Gateway.
BodyModel	string	The body model.	https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab
RequestPath	string	The API path. For example, if the full URL of an API is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, the path is `/object/add`.	/api/billing/test/[type]
RequestHttpMethod	string	The HTTP method. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.	POST
BodyFormat	string	This parameter is valid only when RequestMode is set to MAPPING. For POST and PUT requests, this parameter specifies how data is passed to the server. Valid values: FORM (key-value pairs) and STREAM (byte stream).	STREAM
RequestMode	string	The request mode. Valid values: MAPPING for parameter mapping and PASSTHROUGH for parameter pass-through.	MAPPING
PostBodyDescription	string	The description of the body.	fwefwef
RequestProtocol	string	The protocols supported by the API. You can select multiple protocols. Separate them with commas (,), for example, "HTTP,HTTPS". Valid values: HTTP and HTTPS.	HTTP
EscapePathParam	boolean	Specifies whether to escape path parameters. If this parameter is set to true, `[param]` in the path is treated as a regular character.	true
ServiceConfig	object	The configurations for API requests that are sent from API Gateway to the backend service.
AoneAppName	string	The name of the AONE application.	ib-blank
MockStatusCode	integer	The mock response status code.	200
ContentTypeValue	string	The value of the Content-Type header when you call a backend HTTP service and ContentTypeCatagory is set to DEFAULT or CUSTOM.	application/x-www-form-urlencoded; charset=UTF-8
ServiceProtocol	string	The protocol of the backend service. Only HTTP and HTTPS are supported.	HTTP
ServicePath	string	The path of the backend service. For example, if the full URL of a backend service is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, the ServicePath is `/object/add`.	/object/add
ContentTypeCatagory	string	The policy for setting the value of the Content-Type header when you call the backend HTTP service: DEFAULT: Use the default value of API Gateway. CUSTOM: Use a custom value. CLIENT: Use the Content-Type header of the client request.	CUSTOM
ServiceAddress	string	The address of the backend service. For example, if the full URL of a backend service is `http://api.a.com:8080/object/add?key1=value1&key2=value2`, the ServiceAddress is `http://api.a.com:8080`.	http://api.a.com:8080
Mock	string	Specifies whether to enable mock mode. Valid values: TRUE: Mock mode is enabled. FALSE: 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 add a VPC authorization before you can enable the VPC channel. FALSE: The VPC channel is not enabled.	TRUE
MockResult	string	The returned result in mock mode.	test result
ServiceHttpMethod	string	The HTTP method used to call the backend service. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.	POST
ServiceTimeout	integer	The timeout period of the backend service, in milliseconds.	1000
MockHeaders	object
MockHeader	array<object>	The mock headers.
	object
HeaderValue	string	The value of the HTTP header parameter.	86400
HeaderName	string	The name of the HTTP header parameter.	Content-Length
VpcConfig	object	The configurations of the VPC channel.
VpcId	string	The ID of the VPC.	vpc-2zeafsc3fygk1***
VpcScheme	string	The VPC protocol.	HTTP
InstanceId	string	The ID of the instance in the VPC, such as an ECS instance or a Server Load Balancer instance.	i-bp1h497hkijewv2***
Port	integer	The port number of the instance.	8080
Name	string	The name of the VPC authorization.	glmall-app-test
FunctionComputeConfig	object	The backend configurations when the backend service is Function Compute.
FcType	string	The type of the Function Compute service.	HttpTrigger
RoleArn	string	The ARN of the RAM role that authorizes API Gateway to access Function Compute.	acs:ram::111***:role/aliyunserviceroleforsas
Method	string	The request method.	GET
FcBaseUrl	string	The root path of the Function Compute service.	https://1227**64334133.ap-southeast-1-intal.fc.aliyuncs.com/201*-15/proxy/test**ice.LATEST/testHttp/
ContentTypeValue	string	The value of the Content-Type header when you call the backend Function Compute service and ContentTypeCatagory is set to DEFAULT or CUSTOM.	application/x-www-form-urlencoded; charset=UTF-8
RegionId	string	The region where Function Compute is deployed.	cn-qingdao
OnlyBusinessPath	boolean	Specifies whether the backend receives only the business path.	false
FunctionName	string	The name of the function in Function Compute.	edge_function
ContentTypeCatagory	string	The policy for setting the value of the Content-Type header when you call the backend Function Compute service: DEFAULT: Use the default value of API Gateway. CUSTOM: Use a custom value. CLIENT: Use the Content-Type header of the client request.	DEFAULT
Path	string	The API request path.	/api/offline/cacheData
ServiceName	string	The name of the service in Function Compute.	fcservicename
Qualifier	string	The function alias.	2
TriggerName	string		test1
FcVersion	string
OssConfig	object	The information about the OSS backend.
Key	string	The path of the object or folder stored in OSS.	/folder/test.json
Action	string	The OSS operation. Valid values: GetObject PostObject DeleteObject PutObject HeadObject GetObjectMeta AppendObject	GetObject
OssRegionId	string	The ID of the region where the OSS service is located.	cn-hangzhou
BucketName	string	The OSS bucket.	cbg-db
EventBridgeConfig	object	The EventBridge settings.
EventBus	string	The event bus.	testBus
EventSource	string	The event source.	baas_driver
EventBridgeRegionId	string	The ID of the region where the EventBridge service is located.	cn-beijing
RoleArn	string	The ARN of the RAM role that authorizes API Gateway to access EventBridge.	acs:ram::1933122015759***:role/adminoidcaliyun
OpenIdConnectConfig	object	The configurations for OpenID Connect, which is a third-party identity authentication service.
OpenIdApiType	string	The OpenID Connect mode. Valid values: IDTOKEN: an authorization API that issues tokens. If you set this parameter to this value, you must also set PublicKeyId and PublicKey. BUSINESS: a business API that verifies tokens. If you set this parameter to this value, you must also set IdTokenParamName.	IDTOKEN
IdTokenParamName	string	The name of the parameter that corresponds to the token.	xxx
PublicKeyId	string	The public key ID.	88483727556929326703309904351185815489
PublicKey	string	The public key.	EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92
ErrorCodeSamples	object
ErrorCodeSample	array<object>	Sample error codes returned by the backend service.
	object
Code	string	The error code.	400
Model	string	The model.	[\"*\"]
Message	string	The error message.	Missing the parameter UserId
Description	string	The description.	The UserId parameter is missing from the request.
SystemParameters	object
SystemParameter	array<object>	The system parameters that API Gateway sends to the backend service.
	object
DemoValue	string	A sample 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 position of the parameter. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The name of the corresponding backend parameter.	clientIp
CustomSystemParameters	object
CustomSystemParameter	array<object>	The list of custom system parameters.
	object
DemoValue	string	A sample 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 position of the parameter. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The name of the corresponding backend parameter.	clientIp
ConstantParameters	object
ConstantParameter	array<object>	The constant parameters that API Gateway sends to the backend service.
	object
Description	string	The parameter description.	constance
Location	string	The position of the parameter. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameterName	string	The name of the backend parameter.	constance
ConstantValue	string	The parameter value.	constance
RequestParameters	object
RequestParameter	array<object>	The description of the parameters for an API request that a consumer sends to API Gateway.
	object
JsonScheme	string	The JSON schema for validation when ParameterType is String.	JSON
MaxValue	integer	The maximum parameter value. This parameter is valid when ParameterType is Int, Long, Float, or Double.	123456
ArrayItemsType	string	The type of the array elements.	String
MinValue	integer	The minimum parameter value. This parameter is valid when ParameterType is Int, Long, Float, or Double.	123456
DocShow	string	Specifies whether the documentation is visible. Valid values: PUBLIC and PRIVATE.	PUBLIC
MaxLength	integer	The maximum parameter length. This parameter is valid when ParameterType is String.	123456
DefaultValue	string	The default value.	20
ApiParameterName	string	The parameter name.	age
EnumValue	string	The valid values of the parameter when ParameterType is Int, Long, Float, Double, or String. Separate multiple values with commas (,), for example, 1,2,3,4,9 or A,B,C,E,F.	boy,girl
DemoValue	string	A sample value.	20
Required	string	Specifies whether the parameter is required. Valid values: REQUIRED and OPTIONAL.	OPTIONAL
Description	string	The parameter description.	Age
ParameterType	string	The parameter type. Valid values: String, Int, Long, Float, Double, and Boolean.	String
RegularExpression	string	The regular expression used for validation when ParameterType is String.	xxx
MinLength	integer	The minimum parameter length. This parameter is valid when ParameterType is String.	123456
DocOrder	integer	The sequence number in the documentation.	0
Location	string	The position of the parameter. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ServiceParameters	object
ServiceParameter	array<object>	The description of the parameters for an API request that API Gateway sends to the backend service.
	object
Location	string	The position of the parameter. Valid values: BODY, HEAD, QUERY, and PATH.	HEAD
ParameterType	string	The data type of the backend parameter. Valid values: STRING, NUMBER, and BOOLEAN.	String
ServiceParameterName	string	The name of the backend parameter.	clientIp
ServiceParametersMap	object
ServiceParameterMap	array<object>	The mapping between frontend request parameters and backend request parameters.
	object
RequestParameterName	string	The name of the frontend request parameter. This value must exist in the `RequestParameters` object and match the `ApiParameterName` of a `RequestParameter`.	sex
ServiceParameterName	string	The name of the backend parameter.	sex
DeployedInfos	object
DeployedInfo	array<object>	The publishing status of the API.
	object
StageName	string	The name of the environment. Valid values: RELEASE and TEST.	RELEASE
EffectiveVersion	string	The effective version.	xxx
DeployedStatus	string	The deployment status. Valid values: DEPLOYED (deployed) and NONDEPLOYED (not deployed).	DEPLOYED
TagList	object
Tag	array<object>	The list of tags.
	object
TagKey	string	The tag key.	APP
TagValue	string	The tag value.	value3

Examples

Success response

JSON format

{
  "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",
      "TriggerName": "test1",
      "FcVersion": ""
    },
    "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

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.