All Products
Search
Document Center

API Gateway:DescribeApiHistory

Last Updated:Mar 30, 2026

Queries a specified historical version of a specified API definition.

Operation description

Queries a specified historical version of a specified API definition.

  • This API is intended for API providers.

  • API Gateway records the time and definition of an API every time the API is published. You can use the version number obtained from other operations to query definition details at a certain publication.

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:DescribeApiHistory

get

*ApiGroup

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

None None

Request parameters

Parameter

Type

Required

Description

Example

GroupId

string

No

The ID of the API group. This ID is generated by the system and globally unique.

3013a55c0c44483f984d26df27120513

ApiId

string

Yes

The ID of the API.

dc6e17ee3120404c839bbcd7622ab6ed

StageName

string

Yes

The name of the runtime environment. Valid values:

  • RELEASE

  • TEST: the test environment

  • PRE: the pre-release environment

RELEASE

HistoryVersion

string

Yes

Specifies the version number that you want to query.

20211122155403834

Response elements

Element

Type

Description

Example

object

Status

string

The invocation status of the API.

200

ApiId

string

The ID of the API.

bebf996e4b3d445d83078094b72b0d91

ResultType

string

The type of the data to return.

JSON

WebSocketApiType

string

The type of the two-way communication API. Valid values:

  • COMMON: general APIs

  • REGISTER: registered APIs

  • UNREGISTER: unregistered APIs

  • NOTIFY: downstream notification

COMMON

DisableInternet

boolean

  • Specifies whether to set DisableInternet to true to limit API calls to within the VPC.

  • If you set DisableInternet to false, the limit is lifted. The default value is false when you create an API.

true

ResultBodyModel

string

The return description of the API.

{}

ResultSample

string

The sample response.

{\n \"status\": 0,\n \"data\": {\n \"count\": 1,\n \"list\": [\n \"352\"\n ]\n },\n \"message\": \"success\"\n}

AppCodeAuthType

string

The AppCode authentication type supported. Valid values:

  • DEFAULT: supported after being made available in Alibaba Cloud Marketplace

  • DISABLE: not supported.

  • HEADER : supported only in the Header parameter

  • HEADER_QUERY : supported in the Header or Query parameter.

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 where the API is located.

cn-hangzhou

ForceNonceCheck

boolean

  • Specifies whether to set ForceNonceCheck to true to force the check of X-Ca-Nonce during the request. 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 replay attacks.

  • If you set ForceNonceCheck to false, the check is not performed. The default value is false when you create an API.

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.

{"errorCode":"fail","errorMessage":"param invalid"}

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.

APP

RequestId

string

The ID of the request.

6C87A26A-6A18-4B8E-8099-705278381A2C

Description

string

The description of the API.

根据地区名称查询天气情况

GroupName

string

The name of the API group.

dev_api

GroupId

string

The ID of the API group.

cfb6ef799bf54fffabb0f02019ad2581

DeployedTime

string

The publishing time (UTC) of the API.

2021-06-1113:57:38

StageName

string

The environment in which the API is requested. Valid values:

  • RELEASE: the production environment

  • PRE: the pre-release environment

  • TEST: the test environment

RELEASE

HistoryVersion

string

The historical version number.

20211022134156663

ApiName

string

The name of the API.

测试API

BackendEnable

boolean

Specifies whether to enable backend services.

true

BackendConfig

object

Backend configurations

BackendId

string

The ID of the backend service.

a0305308908c4740aba9cbfd63ba99b7

BackendType

string

The type of the backend service.

HTTP

BackendName

string

The name of the backend service.

zmapi

RequestConfig

object

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

For more information, see RequestConfig.

BodyModel

string

The body model.

https://apigateway.aliyun.com/models/340a127dcc4afd9ab1bf7e947b4095/9e2df550e85b412179ec33e2619eaab

RequestPath

string

API path

/api/billing/test/[type]

RequestHttpMethod

string

The HTTP method. Valid values: GET, POST, DELETE, PUT, HEADER, TRACE, PATCH, CONNECT, and OPTIONS.

POST

BodyFormat

string

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. This parameter takes effect only when the RequestMode parameter is set to MAPPING.

STREAM

RequestMode

string

The request mode. Valid values:

  • MAPPING: Parameters are mapped. Unknown parameters are filtered out.

  • PASSTHROUGH: Parameters are passed through.

  • MAPPING_PASSTHROUGH: Parameters are mapped. Unknown parameters are passed through.

MAPPING

PostBodyDescription

string

The description of the request body.

fwefwef

RequestProtocol

string

The protocol type supported by the API. Valid values: HTTP, HTTPS, and WebSocket. 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.

false

ServiceConfig

object

The information about a backend service call.

VpcId

string

The ID of the VPC.

vpc-uf6kg9x8sx2tbxxxx

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/json

ServiceProtocol

string

The backend service protocol. Currently, only HTTP, HTTPS, and FunctionCompute are supported.

HTTP

ServicePath

string

The path used when you call the backend service.

/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 backend service.

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.

  • FALSE: The VPC channel is not enabled.

You must create the corresponding VPC access authorization before you can enable a VPC channel.

TRUE

MockResult

string

The result returned when the Mock mode is enabled.

test result

ServiceHttpMethod

string

The HTTP request method used when calling the backend service. Valid values: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS, and ANY.

POST

ServiceTimeout

integer

The timeout period of the backend service, in millisecond.

1000

MockHeaders

object

MockHeader

array<object>

The simulated Headers.

object

HeaderValue

string

The values of the HTTP headers.

86400

HeaderName

string

The HTTP headers.

Content-Type

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 IDs of the ELB and SLB instances in the VPC.

i-bp1h497hkijewv2***

Port

integer

The port number that corresponds to the instance.

8080

Name

string

The name of the VPC.

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://122xxxxxxx.fc.aliyun.com/2016xxxx/proxy/testSxxx.xxx/testHttp/

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/json

RegionId

string

The ID of the region.

cn-hangzhou

OnlyBusinessPath

boolean

The backend only receives the service path.

false

FunctionName

string

The function name defined in Function Compute.

domain_business_control

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

Information when the backend service is 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.

phototest02

EventBridgeConfig

object

Configuration items of EventBridge

EventBridgeRegionId

string

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

cn-beijing

EventBus

string

The event bus.

testBus

EventSource

string

The event source of the managed rule.

baas_driver

RoleArn

string

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

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

OpenIdConnectConfig

object

The configuration items of the third-party OpenID Connect authentication method.

OpenIdApiType

string

The configuration of OpenID Connect authentication. 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 of the API.

EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92

ErrorCodeSamples

object

ErrorCodeSample

array<object>

The sample error codes returned by the backend service.

For more information, see ErrorCodeSample.

object

Code

string

The returned error code.

400

Message

string

The returned error message.

MissingParameter

Description

string

The error description.

Missing the parameter UserId

ResultDescriptions

object

ResultDescription

array<object>

The return description of the API.

object

Type

string

The result type.

String

Key

string

The primary key of the result.

groupName

HasChild

boolean

Indicates whether a subnode exists.

true

Description

string

The subnode description.

for_test1

Pid

string

The ID of the parent node.

pid

Mandatory

boolean

Indicates whether the parameter is required.

true

Name

string

The result name.

fwqf

Id

string

The result ID.

id

SystemParameters

object

SystemParameter

array<object>

The common parameters of the APIs, in JSON format.

object

DemoValue

string

The sample value.

192.168.1.1

Description

string

The description.

system parameters description

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

object

CustomSystemParameter

array<object>

The custom system parameters.

object

DemoValue

string

The sample value.

192.168.1.1

Description

string

The parameter description.

balabala

ParameterName

string

The parameter name.

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

object

ConstantParameter

array<object>

The constant parameters.

object

Description

string

The parameter description.

for_test1

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 value of the constant parameter.

constance

RequestParameters

object

RequestParameter

array<object>

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

For more information, see RequestParameter.

object

JsonScheme

string

JSON scheme

{}

MaxValue

integer

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

integer

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

integer

The maximum parameter length when ParameterType is set to String.

123456

DefaultValue

string

The default value.

20

ApiParameterName

string

The name of the parameter in the API request.

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 sample value.

20

Required

string

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

OPTIONAL

Description

string

The parameter description.

modidyTest

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

integer

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

object

ServiceParameter

array<object>

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

For more information, see 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

object

ServiceParameterMap

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.

For more information, see 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

Examples

Success response

JSON format

{
  "Status": "200",
  "ApiId": "bebf996e4b3d445d83078094b72b0d91",
  "ResultType": "JSON",
  "WebSocketApiType": "COMMON",
  "DisableInternet": true,
  "ResultBodyModel": "{}",
  "ResultSample": "{\\n  \\\"status\\\": 0,\\n  \\\"data\\\": {\\n    \\\"count\\\": 1,\\n    \\\"list\\\": [\\n      \\\"352\\\"\\n    ]\\n  },\\n  \\\"message\\\": \\\"success\\\"\\n}",
  "AppCodeAuthType": "HEADER",
  "AllowSignatureMethod": "HmacSHA256",
  "RegionId": "cn-hangzhou",
  "ForceNonceCheck": true,
  "Visibility": "PUBLIC",
  "FailResultSample": "{\"errorCode\":\"fail\",\"errorMessage\":\"param invalid\"}",
  "AuthType": "APP",
  "RequestId": "6C87A26A-6A18-4B8E-8099-705278381A2C",
  "Description": "根据地区名称查询天气情况",
  "GroupName": "dev_api",
  "GroupId": "cfb6ef799bf54fffabb0f02019ad2581",
  "DeployedTime": "2021-06-1113:57:38",
  "StageName": "RELEASE",
  "HistoryVersion": "20211022134156663",
  "ApiName": "测试API",
  "BackendEnable": true,
  "BackendConfig": {
    "BackendId": "a0305308908c4740aba9cbfd63ba99b7",
    "BackendType": "HTTP",
    "BackendName": "zmapi"
  },
  "RequestConfig": {
    "BodyModel": "https://apigateway.aliyun.com/models/340a127dcc4afd9ab1bf7e947b4095/9e2df550e85b412179ec33e2619eaab",
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP",
    "EscapePathParam": false
  },
  "ServiceConfig": {
    "VpcId": "vpc-uf6kg9x8sx2tbxxxx",
    "MockStatusCode": 200,
    "ContentTypeValue": "application/json",
    "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-Type"
        }
      ]
    },
    "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://122xxxxxxx.fc.aliyun.com/2016xxxx/proxy/testSxxx.xxx/testHttp/",
      "ContentTypeValue": "application/json",
      "RegionId": "cn-hangzhou",
      "OnlyBusinessPath": false,
      "FunctionName": "domain_business_control",
      "ContentTypeCatagory": "DEFAULT",
      "Path": "/api/offline/cacheData",
      "ServiceName": "fcservicename",
      "Qualifier": "2"
    },
    "OssConfig": {
      "Key": "/folder/test.json",
      "Action": "GetObject",
      "OssRegionId": "cn-hangzhou",
      "BucketName": "phototest02"
    },
    "EventBridgeConfig": {
      "EventBridgeRegionId": "cn-beijing",
      "EventBus": "testBus",
      "EventSource": "baas_driver",
      "RoleArn": "acs:ram::1933122015759***:role/adminoidcaliyun"
    }
  },
  "OpenIdConnectConfig": {
    "OpenIdApiType": "IDTOKEN",
    "IdTokenParamName": "xxx",
    "PublicKeyId": "88483727556929326703309904351185815489",
    "PublicKey": "EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92"
  },
  "ErrorCodeSamples": {
    "ErrorCodeSample": [
      {
        "Code": "400",
        "Message": "MissingParameter",
        "Description": "Missing the parameter UserId"
      }
    ]
  },
  "ResultDescriptions": {
    "ResultDescription": [
      {
        "Type": "String",
        "Key": "groupName",
        "HasChild": true,
        "Description": "for_test1",
        "Pid": "pid",
        "Mandatory": true,
        "Name": "fwqf",
        "Id": "id"
      }
    ]
  },
  "SystemParameters": {
    "SystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "system parameters description",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "CustomSystemParameters": {
    "CustomSystemParameter": [
      {
        "DemoValue": "192.168.1.1",
        "Description": "balabala",
        "ParameterName": "CaClientIp",
        "Location": "HEAD",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ConstantParameters": {
    "ConstantParameter": [
      {
        "Description": "for_test1",
        "Location": "HEAD",
        "ServiceParameterName": "constance",
        "ConstantValue": "constance"
      }
    ]
  },
  "RequestParameters": {
    "RequestParameter": [
      {
        "JsonScheme": "{}",
        "MaxValue": 123456,
        "ArrayItemsType": "String",
        "MinValue": 123456,
        "DocShow": "PUBLIC",
        "MaxLength": 123456,
        "DefaultValue": "20",
        "ApiParameterName": "age",
        "EnumValue": "boy,girl",
        "DemoValue": "20",
        "Required": "OPTIONAL",
        "Description": "modidyTest",
        "ParameterType": "String",
        "RegularExpression": "xxx",
        "MinLength": 123456,
        "DocOrder": 0,
        "Location": "HEAD"
      }
    ]
  },
  "ServiceParameters": {
    "ServiceParameter": [
      {
        "Location": "HEAD",
        "ParameterType": "String",
        "ServiceParameterName": "clientIp"
      }
    ]
  },
  "ServiceParametersMap": {
    "ServiceParameterMap": [
      {
        "RequestParameterName": "sex",
        "ServiceParameterName": "sex"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.