All Products
Search
Document Center

API Gateway:DescribeApiHistory

Last Updated:Mar 01, 2024

Queries the details of a specified historical version of a specified API definition.

Operation description

Queries the details of 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.

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:DescribeApiHistoryRead
  • All Resources
    *
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
GroupIdstringYes

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

3013a55c0c44483f984d26df27120513
ApiIdstringYes

The ID of the API.

dc6e17ee3120404c839bbcd7622ab6ed
StageNamestringYes

The name of the runtime environment. Valid values:

  • RELEASE
  • TEST: the test environment
  • PRE: the pre-release environment
RELEASE
HistoryVersionstringYes

Specifies the version number that you want to query.

20211122155403834

Response parameters

ParameterTypeDescriptionExample
object
Statusstring

The invocation status of the API.

200
ApiIdstring

The ID of the API.

bebf996e4b3d445d83078094b72b0d91
ResultTypestring

The type of the data to return.

JSON
WebSocketApiTypestring

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

  • COMMON: general APIs
  • REGISTER: registered APIs
  • UNREGISTER: unregistered APIs
  • NOTIFY: downstream notification
COMMON
DisableInternetboolean
  • 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
ResultBodyModelstring

The return description of the API.

{}
ResultSamplestring

The sample response.

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

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

cn-hangzhou
ForceNonceCheckboolean
  • 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
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.

{"errorCode":"fail","errorMessage":"param invalid"}
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.
APP
RequestIdstring

The ID of the request.

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

The description of the API.

Queries weather based on the region name
GroupNamestring

The name of the API group.

dev_api
GroupIdstring

The ID of the API group.

cfb6ef799bf54fffabb0f02019ad2581
DeployedTimestring

The publishing time (UTC) of the API.

2021-06-1113:57:38
StageNamestring

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

  • RELEASE: the production environment
  • PRE: the pre-release environment
  • TEST: the test environment
RELEASE
HistoryVersionstring

The historical version number.

20211022134156663
ApiNamestring

The name of the API.

Backstage_MengMeng Broadcast_Seven Niu Cloud Push Stream Callback_Official
BackendEnableboolean

Specifies whether to enable backend services.

true
BackendConfigobject

Backend configurations

BackendIdstring

The ID of the backend service.

a0305308908c4740aba9cbfd63ba99b7
BackendTypestring

The type of the backend service.

HTTP
BackendNamestring

The name of the backend service.

zmapi
RequestConfigobject

Configuration items of API requests sent by the consumer to API Gateway.

For more information, see RequestConfig .

BodyModelstring

The body model.

https://apigateway.aliyun.com/models/3a240a1XXXXXXXXd9ab1bf7e947b4095/9e2df550e85b4XXXXXXXX619eaab
RequestPathstring

API path

/api/billing/test/[type]
RequestHttpMethodstring

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

POST
BodyFormatstring

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
RequestModestring

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
PostBodyDescriptionstring

The description of the request body.

fwefwef
RequestProtocolstring

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

HTTP
ServiceConfigobject

The information about a backend service call.

VpcIdstring

The ID of the VPC.

vpc-uf6kg9x8sx2tbxxxx
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/json
ServiceProtocolstring

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

HTTP
ServicePathstring

The path used when you call the backend service.

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

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.
  • FALSE: The VPC channel is not enabled.

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

TRUE
MockResultstring

The result returned when the Mock mode is enabled.

test result
ServiceHttpMethodstring

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

POST
ServiceTimeoutinteger

The timeout period of the backend service, in millisecond.

1000
MockHeadersobject []

The simulated Headers.

HeaderValuestring

The value of the HTTP header parameter.

86400
HeaderNamestring

The name of the HTTP header parameter.

Content-Type
VpcConfigobject

Configuration items related to VPC channels

VpcIdstring

The ID of the VPC.

vpc-2zeafsc3fygk1***
VpcSchemestring

The VPC protocol.

HTTP
InstanceIdstring

The IDs of the ELB and SLB instances in the VPC.

i-bp1h497hkijewv2***
Portinteger

The port number that corresponds to the instance.

8080
Namestring

The name of the VPC.

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

The ID of the region.

cn-hangzhou
OnlyBusinessPathboolean

The backend only receives the service path.

false
FunctionNamestring

The function name defined in Function Compute.

domain_business_control
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

Information when the backend service is OSS

Keystring

The stored object or folder path.

ENV
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.

phototest02
EventBridgeConfigobject

Configuration items of EventBridge

EventBridgeRegionIdstring

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

cn-beijing
EventBusstring

The event bus.

testBus
EventSourcestring

The event source of the managed rule.

baas_driver
RoleArnstring

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

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

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

OpenIdApiTypestring

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
IdTokenParamNamestring

The name of the parameter that corresponds to the token.

xxx
PublicKeyIdstring

The ID of the public key.

88483727556929326703309904351185815489
PublicKeystring

The public key of the API.

EB1837F8693CCED0BF750B3AD48467BEB569E780A14591CF92
ErrorCodeSamplesobject []

The sample error codes returned by the backend service.

For more information, see ErrorCodeSample .

Codestring

The error code.

400
Messagestring

The error message.

MissingParameter
Descriptionstring

The description.

Missing the parameter UserId
ResultDescriptionsobject []

The return description of the API.

Typestring

The type of the result.

String
Keystring

The primary key of the result.

groupName
HasChildboolean

Specifies whether a subnode exists.

true
Descriptionstring

The description.

for_test1
Pidstring

The ID of the parent node.

pid
Mandatoryboolean

Specifies whether the parameter is required.

true
Namestring

The name of the result.

fwqf
Idstring

The ID of the result.

id
SystemParametersobject []

The common parameters of the APIs, in JSON format.

DemoValuestring

The sample value of the parameter.

192.168.1.1
Descriptionstring

The description.

system parameters description
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 name of the corresponding backend parameter.

clientIp
CustomSystemParametersobject []

The custom system parameters.

DemoValuestring

Example

192.168.1.1
Descriptionstring

The description of the custom system parameter.

balabala
ParameterNamestring

The name of the custom system parameter.

CaClientIp
Locationstring

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

HEAD
ServiceParameterNamestring

The name of the corresponding backend parameter.

clientIp
ConstantParametersobject []

The constant parameters.

Descriptionstring

The description.

for_test1
Locationstring

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

HEAD
ServiceParameterNamestring

The name of the backend service parameter.

constance
ConstantValuestring

The constant value.

constance
RequestParametersobject []

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

For more information, see RequestParameter .

JsonSchemestring

JSON scheme

{}
MaxValuelong

The maximum parameter value when ParameterType is set to Int, Long, Float, or Double.

123456
ArrayItemsTypestring

The type of the array element.

String
MinValuelong

The minimum parameter value when ParameterType is set to Int, Long, Float, or Double.

123456
DocShowstring

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

PUBLIC
MaxLengthlong

The maximum parameter length when ParameterType is set to String.

123456
DefaultValuestring

Default value

20
ApiParameterNamestring

The name of the API parameter.

age
EnumValuestring

The hash values that can be entered when ParameterType is set to Int, Long, Float, Double, or String. Separate different values with commas (,), such as 1,2,3,4,9 or A,B,C,E,F.

boy,girl
DemoValuestring

Examples

20
Requiredstring

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

OPTIONAL
Descriptionstring

The description.

modidyTest
ParameterTypestring

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

String
RegularExpressionstring

The regular expression used for parameter validation when ParameterType is set to String.

xxx
MinLengthlong

The minimum parameter length when ParameterType is set to String.

123456
DocOrderinteger

The order 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.

For more information, see ServiceParameter .

Locationstring

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

HEAD
ParameterTypestring

The data type of the back-end service parameter.

String
ServiceParameterNamestring

The name of the backend service parameter.

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.

For more information, see ServiceParameterMap .

RequestParameterNamestring

The corresponding frontend parameter. It must be included in RequestParametersObject and matches ApiParameterName in RequestParameter data.

sex
ServiceParameterNamestring

The name of the backend service parameter.

sex

Examples

Sample success responses

JSONformat

{
  "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": "Queries weather based on the region name\n",
  "GroupName": "dev_api",
  "GroupId": "cfb6ef799bf54fffabb0f02019ad2581",
  "DeployedTime": "2021-06-1113:57:38",
  "StageName": "RELEASE",
  "HistoryVersion": "20211022134156663",
  "ApiName": "Backstage_MengMeng Broadcast_Seven Niu Cloud Push Stream Callback_Official\n",
  "BackendEnable": true,
  "BackendConfig": {
    "BackendId": "a0305308908c4740aba9cbfd63ba99b7",
    "BackendType": "HTTP",
    "BackendName": "zmapi"
  },
  "RequestConfig": {
    "BodyModel": "https://apigateway.aliyun.com/models/3a240a1XXXXXXXXd9ab1bf7e947b4095/9e2df550e85b4XXXXXXXX619eaab",
    "RequestPath": "/api/billing/test/[type]",
    "RequestHttpMethod": "POST",
    "BodyFormat": "STREAM",
    "RequestMode": "MAPPING",
    "PostBodyDescription": "fwefwef",
    "RequestProtocol": "HTTP"
  },
  "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": "ENV",
      "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

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

Change history

Change timeSummary of changesOperation
No change history