All Products
Search

This Product

    Describe an API

    Document Center
    Product Details

    Describe an API

    Last Updated: Feb 19, 2019

    Description

    For querying the definition of an API.

    • The interface is intended for API activators.
    • It is used to query the definition of a specified API.

    Request parameters

    Name Type Required? Description
    Action String Yes Operation interface, which is a required parameter; value: DescribeApi.
    GroupId String No ID of the group where the API is located.
    ApiId String Yes ID of the API.

    Return parameters

    Name Type Description
    RequestId String ID of the current API creation request.
    RegionId String ID of the region of the API.
    ApiId String ID of the API.
    ApiName String Name of the API, which is unique in the group.
    GroupId String ID of the group where the API is located.
    GroupName String Name of the group of the API.
    Visibility String Indicates whether the API is public; values:
    • PUBLIC: If the type is set to public, this API’s launch stage will be shown on the Discover APIs console page for all users.
    • PRIVATE: When an API group is available on the Cloud Marketplace, APIs with the private type are unavailable.
    AuthType String API security authorization type; values:
    • App: Only authorized apps can call the API.
    • ANONYMOUS: The API can be called anonymously. In such a mode, you must note the following:
      • Anyone who can obtain this API service information can call this API. The gateway does not authenticate the identity of callers and cannot set traffic limits for individual users. If you activate this API, set API-based throttling.
      • ANONYMOUS API: We do not suggest making anonymous APIs available on the Cloud Marketplace. The gateway cannot meter callers separately and cannot control the number of calls. If the group including this API is to be added to the Cloud Marketplace, we suggest you move this API to another group, set its type to private, or select the Alibaba Cloud App certification method.
    ResultType String Format of the reply returned by the backend service. Currently, allowed formats are JSON, TEXT, BINARY, XML, and HTML.
    ResultSample String Sample of the reply returned by the backend service.
    FailResultSample String Sample of the reply failure returned by the backend service.
    CreateTime String API creation time.
    ModifyTime String API last modification time.
    Description String API description.
    Mock String Indicates whether the Mock mode is used; values:
    OPEN: The Mock mode is enabled. CLOSE: The Mock mode is disabled.
    MockResult String Results returned when the Mock mode is enabled.
    ErrorCodeSamples ErrorCodeSamples Sample of the error code returned by the backend service.
    SystemParameters SystemParameters System parameters sent by the gateway to a backend service.
    ConstantParameters ConstantParameter Constant parameters sent by the gateway to a backend service.
    RequestParametersObject RequestParameters Description on parameters of the API request sent by a consumer to the gateway.
    ServiceParametersObject ServiceParameters Description on parameters of the API request sent by the gateway to a backend service.
    ParametersMapObject ServiceParametersMap The mappings between parameters of a request sent by a consumer to the gateway and parameters of a request sent by the gateway to a backend service.
    DeployedInfos DeployedInfo Deployment status of the API.
    RequestConfig RequestConfig Configuration items of the API request sent by a consumer to the gateway.
    ServiceConfig ServiceConfig Configuration items of the API request sent by the gateway to a backend service.

    Examples

    Request example

    1. https://apigateway.cn-qingdao.aliyuncs.com/?Action=DescribeApi
    2. &ApiId=8afff6c8c4c6447abb035812e4d66b65
    4. &<Public request parameters>

    Example returned

    XML format

    1. <DescribeApiResponse>
    2.     <RequestId>D0FF585F-7966-40CF-BC60-75DB070B23D5</RequestId>
    3.     <RegionId>cn-qingdao</RegionId>
    4.     <Description>Api description</Description>
    5.     <ApiName>ApiName</ApiName>
    6.     <CreatedTime>2016-07-28T09:50:43Z</CreatedTime>
    7.     <Mock>CLOSED</Mock>
    8.     <GroupName>ApiTest</GroupName>
    9.     <ModifiedTime>2016-07-28T13:13:12Z</ModifiedTime>
    10.     <ServiceParametersObject>
    11.         <ServiceParam>
    12.             <ServiceParameterName>age</ServiceParameterName>
    13.             <Type>Number</Type>
    14.             <Location>head</Location>
    15.         </ServiceParam>
    16.         <ServiceParam>
    17.             <ServiceParameterName>sex</ServiceParameterName>
    18.             <Type>String</Type>
    19.             <Location>query</Location>
    20.         </ServiceParam>
    21.         <ServiceParam>
    22.             <ServiceParameterName>userId</ServiceParameterName>
    23.             <Type>Number</Type>
    24.             <Location>path</Location>
    25.         </ServiceParam>
    26.         <ServiceParam>
    27.             <ServiceParameterName>clientIp</ServiceParameterName>
    28.             <Type>String</Type>
    29.             <Location>head</Location>
    30.         </ServiceParam>
    31.         <ServiceParam>
    32.             <ServiceParameterName>constance</ServiceParameterName>
    33.             <Type>String</Type>
    34.             <Location>head</Location>
    35.         </ServiceParam>
    36.     </ServiceParametersObject>
    37.     <ConstantParameters>
    38.         <ConstantParameter>
    39.             <ServiceParameterName>constance</ServiceParameterName>
    40.             <Description>constance</Description>
    41.             <Location>HEAD</Location>
    42.             <ConstantValue>constance</ConstantValue>
    43.         </ConstantParameter>
    44.     </ConstantParameters>
    45.     <GroupId>08ae4aa0f95e4321849ee57f4e0b3077</GroupId>
    46.     <SystemParameters>
    47.         <SystemParameter>
    48.             <ServiceParameterName>clientIp</ServiceParameterName>
    49.             <Description> Client IP address</Description>
    50.             <DemoValue>192.168.1.1</DemoValue>
    51.             <Location>HEAD</Location>
    52.             <ParameterName>CaClientIp</ParameterName>
    53.         </SystemParameter>
    54.     </SystemParameters>
    55.     <RequestParametersObject>
    56.         <RequestParam>
    57.             <Required>OPTIONAL</Required>
    58.             <MinValue>18</MinValue>
    59.             <Description> Age</Description>
    60.             <DemoValue>20</DemoValue>
    61.             <ParameterType>NUMBER</ParameterType>
    62.             <ApiParameterName>age</ApiParameterName>
    63.             <DocShow>PUBLIC</DocShow>
    64.             <DefaultValue>20</DefaultValue>
    65.             <Location>HEAD</Location>
    66.             <MaxValue>100</MaxValue>
    67.             <DocOrder>0</DocOrder>
    68.         </RequestParam>
    69.         <RequestParam>
    70.             <Required>OPTIONAL</Required>
    71.             <Description> Gender</Description>
    72.             <DemoValue>boy</DemoValue>
    73.             <ParameterType>STRING</ParameterType>
    74.             <ApiParameterName>sex</ApiParameterName>
    75.             <DocShow>PUBLIC</DocShow>
    76.             <DefaultValue>boy</DefaultValue>
    77.             <Location>QUERY</Location>
    78.             <EnumValue>boy,girl</EnumValue>
    79.             <DocOrder>0</DocOrder>
    80.         </RequestParam>
    81.         <RequestParam>
    82.             <Required>REQUIRED</Required>
    83.             <MinValue>10000000</MinValue>
    84.             <ParameterType>NUMBER</ParameterType>
    85.             <ApiParameterName>userId</ApiParameterName>
    86.             <DocShow>PUBLIC</DocShow>
    87.             <Location>PATH</Location>
    88.             <MaxValue>100000000</MaxValue>
    89.             <DocOrder>0</DocOrder>
    90.         </RequestParam>
    91.     </RequestParametersObject>
    92.     <DeployedInfos>
    93.         <DeployedInfo>
    94.             <DeployedStatus>NONDEPLOYED</DeployedStatus>
    95.             <StageName>TEST</StageName>
    96.         </DeployedInfo>
    97.         <DeployedInfo>
    98.             <DeployedStatus>NONDEPLOYED</DeployedStatus>
    99.             <StageName>RELEASE</StageName>
    100.         </DeployedInfo>
    101.     </DeployedInfos>
    102.     <ServiceConfig>
    103.         <ServiceProtocol>HTTP</ServiceProtocol>
    104.         <ServiceTimeout>1000</ServiceTimeout>
    105.         <ServiceAddress>http://www.customerdomain.com</ServiceAddress>
    106.         <ServicePath>/v3/getUserTest/[userId]</ServicePath>
    107.         <ServiceHttpMethod>GET</ServiceHttpMethod>
    108.     </ServiceConfig>
    109.     <RequestId>D0FF585F-7966-40CF-BC60-75DB070B23D5</RequestId>
    110.     <RegionId>cn-qingdao</RegionId>
    111.     <RequestConfig>
    112.         <RequestHttpMethod>GET</RequestHttpMethod>
    113.         <RequestProtocol>HTTP</RequestProtocol>
    114.         <RequestPath>/v3/getUserTest/[userId]</RequestPath>
    115.     </RequestConfig>
    116.     <Visibility>PUBLIC</Visibility>
    117.     <ParametersMapObject>
    118.         <ServiceParameterMap>
    119.             <ServiceParameterName>sex</ServiceParameterName>
    120.             <RequestParameterName>sex</RequestParameterName>
    121.         </ServiceParameterMap>
    122.         <ServiceParameterMap>
    123.             <ServiceParameterName>age</ServiceParameterName>
    124.             <RequestParameterName>age</RequestParameterName>
    125.         </ServiceParameterMap>
    126.         <ServiceParameterMap>
    127.             <ServiceParameterName>userId</ServiceParameterName>
    128.             <RequestParameterName>userId</RequestParameterName>
    129.         </ServiceParameterMap>
    130.     </ParametersMapObject>
    131.     <ErrorCodeSamples>
    132.         <ErrorCodeSample>
    133.             <Code>400</Code>
    134.             <Message>Missing the parameter UserId</Message>
    135.             <Description> Request where the parameter UserId is missing</Description>
    136.         </ErrorCodeSample>
    137.     </ErrorCodeSamples>
    138.     <ApiId>8afff6c8c4c6447abb035812e4d66b65</ApiId>
    139.     <AuthType>APP</AuthType>
    140.     <ResultType>HTML</ResultType>
    141.     <ResultSample>200</ResultSample>
    142.     <FailResultSample>400</FailResultSample>
    144. </DescribeApiResponse>

    JSON format

    1. {
    2.     "RequestId":D0FF585F-7966-40CF-BC60-75DB070B23D5,
    3.     "RegionId":cn-qingdao,
    4.     "Description": "billingTest001",
    5.     "ApiName": "billingTest001",
    6.     "CreatedTime": "2016-07-01T09:18:20Z",
    7.     "Mock": "CLOSED",
    8.     "GroupName": "billingTest",
    9.     "ModifiedTime": "2016-07-21T03:52:12Z",
    10.     "ServiceParametersObject": {
    11.         "ServiceParam": [
    12.             {
    13.                 "ServiceParameterName": "headerParam",
    14.                 "Type": "String",
    15.                 "Location": "head"
    16.             },
    17.             {
    18.                 "ServiceParameterName": "queryparam",
    19.                 "Type": "String",
    20.                 "Location": "query"
    21.             },
    22.             {
    23.                 "ServiceParameterName": "NumberParam",
    24.                 "Type": "Number",
    25.                 "Location": "query"
    26.             },
    27.             {
    28.                 "ServiceParameterName": "type",
    29.                 "Type": "String",
    30.                 "Location": "path"
    31.             },
    32.             {
    33.                 "ServiceParameterName": "clientIp",
    34.                 "Type": "String",
    35.                 "Location": "head"
    36.             },
    37.             {
    38.                 "ServiceParameterName": "constantParam",
    39.                 "Type": "String",
    40.                 "Location": "query"
    41.             }
    42.         ]
    43.     },
    44.     "ConstantParameters": {
    45.         "ConstantParameter": [
    46.             {
    47.                 "ServiceParameterName": "constantParam",
    48.                 "Description": "constant",
    49.                 "Location": "QUERY",
    50.                 "ConstantValue": "constant"
    51.             }
    52.         ]
    53.     },
    54.     "GroupId": "4a3f3050b9c5469bb685bdd29e571be1",
    55.     "SystemParameters": {
    56.         "SystemParameter": [
    57.             {
    58.                 "ServiceParameterName": "clientIp",
    59.                 "Description": " Client IP address",
    60.                 "DemoValue": "192.168.1.1",
    61.                 "Location": "HEAD",
    62.                 "ParameterName": "CaClientIp"
    63.             }
    64.         ]
    65.     },
    66.     "RequestParametersObject": {
    67.         "RequestParam": [
    68.             {
    69.                 "Required": "OPTIONAL",
    70.                 "Description": "head param",
    71.                 "DemoValue": "headparm",
    72.                 "ParameterType": "STRING",
    73.                 "ApiParameterName": "headerParam",
    74.                 "DocShow": "PUBLIC",
    75.                 "DefaultValue": "",
    76.                 "Location": "HEAD",
    77.                 "EnumValue": "head",
    78.                 "DocOrder": 0
    79.             },
    80.             {
    81.                 "Required": "REQUIRED",
    82.                 "ParameterType": "STRING",
    83.                 "ApiParameterName": "queryparam",
    84.                 "DocShow": "PUBLIC",
    85.                 "DefaultValue": "",
    86.                 "Location": "QUERY",
    87.                 "DocOrder": 0
    88.             },
    89.             {
    90.                 "Required": "OPTIONAL",
    91.                 "MinValue": 1,
    92.                 "Description": "number param",
    93.                 "DemoValue": "10",
    94.                 "ParameterType": "NUMBER",
    95.                 "ApiParameterName": "NumberParam",
    96.                 "DocShow": "PUBLIC",
    97.                 "DefaultValue": "10",
    98.                 "Location": "QUERY",
    99.                 "MaxValue": 100,
    100.                 "DocOrder": 0
    101.             },
    102.             {
    103.                 "Required": "REQUIRED",
    104.                 "ParameterType": "STRING",
    105.                 "ApiParameterName": "type",
    106.                 "DocShow": "PUBLIC",
    107.                 "Location": "PATH",
    108.                 "DocOrder": 0
    109.             }
    110.         ]
    111.     },
    112.     "DeployedInfos": {
    113.         "DeployedInfo": [
    114.             {
    115.                 "DeployedStatus": "NONDEPLOYED",
    116.                 "StageName": "TEST"
    117.             },
    118.             {
    119.                 "DeployedStatus": "DEPLOYED",
    120.                 "StageName": "RELEASE",
    121.                 "EffectiveVersion": "20160721115223375"
    122.             }
    123.         ]
    124.     },
    125.     "ServiceConfig": {
    126.         "ServiceProtocol": "HTTP",
    127.         "ServiceTimeout": 10000,
    128.         "ServiceAddress": "http://120.55.69.157:8080",
    129.         "ServicePath": "/web/cloudapi/[type]",
    130.         "ServiceHttpMethod": "POST"
    131.     },
    132.     "RequestId": "415F037A-94C2-4100-B17A-F3C514CA1391",
    133.     "RegionId": "cn-qingdao",
    134.     "RequestConfig": {
    135.         "RequestHttpMethod": "POST",
    136.         "RequestProtocol": "HTTP",
    137.         "PostBodyDescription": "fwefwef",
    138.         "BodyFormat": "STREAM",
    139.         "RequestPath": "/api/billing/test/[type]"
    140.     },
    141.     "Visibility": "PUBLIC",
    142.     "ParametersMapObject": {
    143.         "ServiceParameterMap": [
    144.             {
    145.                 "ServiceParameterName": "headerParam",
    146.                 "RequestParameterName": "headerParam"
    147.             },
    148.             {
    149.                 "ServiceParameterName": "queryparam",
    150.                 "RequestParameterName": "queryparam"
    151.             },
    152.             {
    153.                 "ServiceParameterName": "NumberParam",
    154.                 "RequestParameterName": "NumberParam"
    155.             },
    156.             {
    157.                 "ServiceParameterName": "type",
    158.                 "RequestParameterName": "type"
    159.             }
    160.         ]
    161.     },
    162.     "ErrorCodeSamples": {
    163.         "ErrorCodeSample": [
    164.             {
    165.                 "Code": "400",
    166.                 "Message": "Missing the parameter UserId",
    167.                 "Description": " Request where the parameter UserId is missing"
    168.             }
    169.         ]
    170.     },
    171.     "ApiId": "e77fd9257b1d436a806fe23c649300a0",
    172.     "AuthType": "APP",
    173.     "ResultType": "JSON",
    174.     "ResultSample": "fwef",
    175.     "FailResultSample": "400"
    176. }