All Products
Search
Document Center

API Gateway:DescribeApi

Last Updated:Mar 01, 2024

Queries the definition of a specified API.

Operation description

  • This operation is intended for API providers.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

  • Operation: the value that you can use in the Action element to specify the operation on a resource.
  • Access level: the access level of each operation. The levels are read, write, and list.
  • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
    • The required resource types are displayed in bold characters.
    • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
  • Condition Key: the condition key that is defined by the cloud service.
  • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
OperationAccess levelResource typeCondition keyAssociated operation
apigateway:DescribeApiRead
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
GroupIdstringNo

The ID of the API group.

123
ApiIdstringYes

The ID of the API.

8afff6c8c4c6447abb035812e4d66b65

Response parameters

ParameterTypeDescriptionExample
object
ApiIdstring

The ID of the API.

8afff6c8c4c6447abb035812e4d66b65
ResultTypestring

The format of the response from the backend service. Valid values: JSON, TEXT, BINARY, XML, and HTML.

JSON
WebSocketApiTypestring

The type of the two-way communication API.

  • COMMON: common API
  • REGISTER: registered API
  • UNREGISTER: unregistered API
  • NOTIFY: downstream notification API
COMMON
DisableInternetboolean

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
ResultBodyModelstring

The returned description of the API.

{}
ResultSamplestring

The sample response from the backend service.

200
AppCodeAuthTypestring

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
AllowSignatureMethodstring

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
RegionIdstring

The region ID of the API.

cn-qingdao
ForceNonceCheckboolean

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
Visibilitystring

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
FailResultSamplestring

The sample error response from the backend service.

400
AuthTypestring

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
ModifiedTimestring

The last modification time of the API.

2016-07-28T13:13:12Z
RequestIdstring

The ID of the request.

D0FF585F-7966-40CF-BC60-75DB070B23D5<
Descriptionstring

The description of the API.

Api description
GroupNamestring

The name of the API group.

ApiTest
GroupIdstring

The ID of the API group.

08ae4aa0f95e4321849ee57f4e0b3077
Mockstring

Specifies whether to enable the Mock mode. Valid values:

  • OPEN: The Mock mode is enabled.
  • CLOSED: The Mock mode is not enabled.
CLOSED
MockResultstring

The result returned for service mocking.

test result
CreatedTimestring

The creation time of the API.

2016-07-28T09:50:43Z
ApiNamestring

The name of the API, which is unique in the group.

ApiName
BackendEnableboolean

Specifies whether to enable backend services.

true
BackendConfigobject

Backend configurations

BackendIdstring

The ID of the backend service.

0038e00c3dca44fcba3a94015d8f5bbf
BackendTypestring

Backend service type

HTTP
BackendNamestring

The name of the backend service.

testoss
RequestConfigobject

The configuration items of API requests sent by the consumer to API Gateway.

BodyModelstring

The body model.

https://apigateway.aliyun.com/models/3a240a127dcc4afd9ab1bf7e947b4095/9e2df550e85b4121a79ec33e2619eaab
RequestPathstring

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]
RequestHttpMethodstring

The HTTP method used to make the request. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.

POST
BodyFormatstring

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
RequestModestring

The request mode. Valid values: MAPPING and PASSTHROUGH.

MAPPING
PostBodyDescriptionstring

The description of the request body.

fwefwef
RequestProtocolstring

The protocol type supported by the API. Valid values: HTTP and HTTPS. Separate multiple values with commas (,), such as "HTTP,HTTPS".

HTTP
ServiceConfigobject

The configuration items of API requests that API Gateway sends to the backend service.

AoneAppNamestring

The application name in AONE.

ib-blank
MockStatusCodeinteger

The status code returned for service mocking.

200
ContentTypeValuestring

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
ServiceProtocolstring

The protocol used by the backend service. Valid values: HTTP and HTTPS.

HTTP
ServicePathstring

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
ContentTypeCatagorystring

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
ServiceAddressstring

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
Mockstring

Specifies whether to enable the Mock mode. Valid values:

  • TRUE: The Mock mode is enabled.
  • FALSE: The Mock mode is not enabled.
TRUE
ServiceVpcEnablestring

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
MockResultstring

The result returned when the Mock mode is enabled.

test result
ServiceHttpMethodstring

The HTTP method used to call a backend service. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.

POST
ServiceTimeoutinteger

The timeout period of the backend service. Unit: milliseconds.

1000
MockHeadersobject []

The simulated headers.

HeaderValuestring

The value of the HTTP header.

86400
HeaderNamestring

The name of the HTTP header.

Content-Length
VpcConfigobject

Configuration items related to VPC channels

VpcIdstring

The ID of the VPC.

vpc-2zeafsc3fygk1***
VpcSchemestring

The VPC protocol.

HTTP
InstanceIdstring

The ID of the ECS or SLB instance in the VPC.

i-bp1h497hkijewv2***
Portinteger

The port number that corresponds to the instance.

8080
Namestring

The name of the VPC access authorization.

glmall-app-test
FunctionComputeConfigobject

Backend configuration items when the backend service is Function Compute

FcTypestring

The type of the Function Compute instance.

HttpTrigger
RoleArnstring

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
Methodstring

The request method.

GET
FcBaseUrlstring

The root path of Function Compute.

https://1227****64334133.ap-southeast-1-int***al.fc.aliyuncs.com/201****-15/proxy/test****ice.LATEST/testHttp/
ContentTypeValuestring

The value of the ContentType header when the ContentTypeCatagory parameter is set to DEFAULT or CUSTOM.

application/x-www-form-urlencoded; charset=UTF-8
RegionIdstring

The region where the Function Compute instance is located.

cn-qingdao
OnlyBusinessPathboolean

The backend only receives the service path.

false
FunctionNamestring

The function name defined in Function Compute.

edge_function
ContentTypeCatagorystring

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
Pathstring

The API request path.

/api/offline/cacheData
ServiceNamestring

The service name defined in Function Compute.

fcservicename
Qualifierstring

The alias of the function.

2
OssConfigobject

The information returned when the backend service is Object Storage Service (OSS).

Keystring

The stored object or folder path.

/folder/test.json
Actionstring

The operation options on OSS. Valid values:

  • GetObject
  • PostObject
  • DeleteObject
  • PutObject
  • HeadObject
  • GetObjectMeta
  • AppendObject
GetObject
OssRegionIdstring

The ID of the region where the OSS instance is located.

cn-hangzhou
BucketNamestring

The OSS bucket.

cbg-db
EventBridgeConfigobject

Configuration items of EventBridge

EventBusstring

The event bus.

testBus
EventSourcestring

The event source.

baas_driver
EventBridgeRegionIdstring

The ID of the region where the EventBridge instance is located.

cn-beijing
RoleArnstring

The Arn that is authorized by a RAM user to EventBridge.

acs:ram::1933122015759***:role/adminoidcaliyun
OpenIdConnectConfigobject

Configuration items of the third-party OpenID Connect authentication method

OpenIdApiTypestring

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
IdTokenParamNamestring

The name of the parameter that corresponds to the token.

xxx
PublicKeyIdstring

The ID of the public key.

88483727556929326703309904351185815489
PublicKeystring

The public key.

EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92
ErrorCodeSamplesobject []

The sample error codes returned by the backend service.

Codestring

The returned error code.

400
Modelstring

The model.

[\"*\"]
Messagestring

The returned error message.

Missing the parameter UserId
Descriptionstring

The error description.

The UserId parameter is missing from the request.
SystemParametersobject []

System parameters sent by API Gateway to the backend service

DemoValuestring

The example value.

192.168.1.1
Descriptionstring

The parameter description.

Client IP Address
ParameterNamestring

The name of the system parameter. Valid values: CaClientIp, CaDomain, CaRequestHandleTime, CaAppId, CaRequestId, CaHttpSchema, and CaProxy.

CaClientIp
Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD
ServiceParameterNamestring

The mapped parameter name in the backend service.

clientIp
CustomSystemParametersobject []

Custom system parameters

DemoValuestring

The example value.

192.168.1.1
Descriptionstring

The parameter description.

Client IP Address
ParameterNamestring

The name of the system parameter. Valid values: CaClientIp, CaDomain, CaRequestHandleTime, CaAppId, CaRequestId, CaHttpSchema, and CaProxy.

CaClientIp
Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD
ServiceParameterNamestring

The mapped parameter name in the backend service.

clientIp
ConstantParametersobject []

System parameters sent by API Gateway to the backend service

Descriptionstring

The parameter description.

constance
Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD
ServiceParameterNamestring

The mapped parameter name in the backend service.

constance
ConstantValuestring

The constant parameter value.

constance
RequestParametersobject []

The parameters of API requests sent by the consumer to API Gateway.

JsonSchemestring

The JSON Schema used for JSON validation when ParameterType is set to String.

JSON
MaxValuelong

The maximum value of the parameter if the ParameterType parameter is set to Int, Long, Float, or Double.

123456
ArrayItemsTypestring

The type of the array element.

String
MinValuelong

The minimum value of the parameter if the ParameterType parameter is set to Int, Long, Float, or Double.

123456
DocShowstring

Indicates whether the document is public. Valid values: PUBLIC and PRIVATE.

PUBLIC
MaxLengthlong

The maximum length of the parameter value if the ParameterType parameter is set to String.

123456
DefaultValuestring

The default value.

20
ApiParameterNamestring

The parameter name.

age
EnumValuestring

The hash values that can be specified if the ParameterType parameter is set to Int, Long, Float, Double, or String. Separate multiple hash values with commas (,). Examples: 1,2,3,4,9 and A,B,C,E,F.

boy,girl
DemoValuestring

The example value.

20
Requiredstring

Indicates whether the parameter is required. Valid values: REQUIRED and OPTIONAL.

OPTIONAL
Descriptionstring

The parameter description.

Age
ParameterTypestring

The data type of the parameter. Valid values: String, Int, Long, Float, Double, and Boolean.

String
RegularExpressionstring

The regular expression that is used to validate the parameter if the ParameterType parameter is set to String.

xxx
MinLengthlong

The minimum length of the parameter value if the ParameterType parameter is set to String.

123456
DocOrderinteger

The order in which the parameter is sorted in the document.

0
Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD
ServiceParametersobject []

The parameters of API requests sent by API Gateway to the backend service.

Locationstring

The parameter location. Valid values: BODY, HEAD, QUERY, and PATH.

HEAD
ParameterTypestring

The data type of the parameter. Valid values: STRING, NUMBER, and BOOLEAN.

String
ServiceParameterNamestring

The mapped parameter name in the backend service.

clientIp
ServiceParametersMapobject []

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.

RequestParameterNamestring

The name of the frontend parameter. The name must be included in RequestParametersObject and match ApiParameterName in RequestParameters.

sex
ServiceParameterNamestring

The mapped parameter name in the backend service.

sex
DeployedInfosobject []

The API publishing status.

StageNamestring

The environment to which the API is published. Valid values: RELEASE and TEST.

RELEASE
EffectiveVersionstring

The effective version.

xxx
DeployedStatusstring

The deployment status. Valid values: DEPLOYED and NONDEPLOYED.

DEPLOYED

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"
  },
  "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"
      }
    ]
  }
}

Error codes

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

Change history

Change timeSummary of changesOperation
2023-07-11The response structure of the API has changedsee changesets
Change itemChange content
Output ParametersThe response structure of the API has changed.