GET /api/apis/versions/{APIVersionID}/definition/{Specification}

GET /api/apis/versions/{APIVersionID}/definition/{Specification}/{IncludeDocId}

Returns generated API definition document for the specified API version. With the optional IncludeDocId parameter, returns the generated API definition document in the specified format.

Authorization Roles/Permissions: User must have read permission for the API, per the visibility rules below.

Visibility rules for generated API definition document: The visibility behavior varies according to the specification for the API, as follows:

  • RAML 0.8/WADL/WSDL documents: This operation does not support applying visibility scopes to specific content within RAML/WADL/WSDL documents. The platform returns these documents to the user only if the user has permission for the entire API. If the user has partial or no visibility permission for the API, the platform returns an Unauthorized message.
  • Swagger 2.0 or 1.2: The operation returns the Swagger document with the information that the user has visibility to see. In this scenario, if the user has visibility to certain parts of the API, but not others, the user will see the parts that he or she has permission to view.

Note: WSDL is generally used for SOAP rather than REST APIs. If you're retrieving the API definition in WSDL format for a REST API it will include proprietary extensions for the Akana platform. For SOAP services it will be standard WSDL.

This topic includes the following sections:

HTTP Method

GET

Back to top

URL

https://{hostname}/api/apis/versions/{APIVersionID}/definition/{Specification}/[{IncludeDocId}][?Environment={Environment}]

Back to top

Sample Request #1

The example below shows a request for the Swagger document for an API set up on the platform, in the Live implementation. The API is a subset of the Swagger Petstore API. For the corresponding response, see Sample Response #1.

Request URL

https://{hostname}/api/apis/versions/be75b6a5-2e86-4ede-a90e-ce92de827b0c.acmepaymentscorp/definition/swagger?Environment=Production

Sample request headers

GET /api/apis/versions/be75b6a5-2e86-4ede-a90e-ce92de827b0c.acmepaymentscorp/definition/swagger?Environment=Production HTTP/1.1
Host: {hostname}
Accept: application/json, text/javascript, */*; q=0.01
X-Csrf-Token_{tenant}: {TokenID}
Cookie: AtmoAuthToken_{tenant}=TokenID{ID}

Sample request body

Not applicable.

Sample Request #2

The examples below show requests for the documentation for an API set up on the platform, that is a subset of the Swagger API. The first four use the optional IncludeDocId parameter, and the last does not. For the corresponding responses, see Sample Response #2.

Request URL: Swagger 1.2

https://{hostname}/api/apis/versions/af5da6b1-2dfb-45ff-8803-07f9cf63143a.acmepaymentscorp/definition/swagger1_2/pet
Accept: application/json

Request URL: Swagger 2.0

https://{hostname}/api/apis/versions/af5da6b1-2dfb-45ff-8803-07f9cf63143a.acmepaymentscorp/definition/swagger/pet
Accept: application/json

Request URL: RAML 0.8

https://{hostname}/api/apis/versions/af5da6b1-2dfb-45ff-8803-07f9cf63143a.acmepaymentscorp/definition/raml/pet
Accept: application/raml+yaml

Request URL: WADL

https://{hostname}/api/apis/versions/af5da6b1-2dfb-45ff-8803-07f9cf63143a.acmepaymentscorp/definition/wadl/pet
Accept: application/vnd.sun.wadl+xml

Request URL: WSDL

https://{hostname}/api/apis/versions/d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp/definition/wsdl

No Accept header specification needed.

Back to top

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept

The Accept header is ignored; the media type is determined by the specification. Use a generic value such as */*, specify an appropriate value for the specification you're using, or leave blank. For example:

  • RAML 0.8: application/raml+yaml
  • Swagger: application/json
  • WADL: application/vnd.sun.wadl+xml
  • WSDL: none needed

Back to top

Request Parameters

Parameter Parm Type Data Type Required Description
APIVersionID Path string Required The unique ID for a specific API version.
Specification Path string Required

The specification to be used in generating the API definition document. Valid values:

  • swagger (defaults to swagger2 which is Swagger 2.0)
  • swagger1_2
  • raml
  • wadl
  • wsdl
IncludeDocId Path string Optional For Swagger 1.2 or WSDL, a description document might import, or include, another document. In that case, the main document will have an import statement with the IncludeDocId parameter. This allows the client to fetch the imported files.
Environment Query string Optional Optionally, specify the implementation (Sandbox or Live) for which you want the API description document. If not specified, this parameter returns the API definition for the Live implementation, if it exists, and for the Sandbox implementation, if there is no Live implementation.

Back to top

Response

If successful, this operation returns HTTP status code 200, with the requested generated API definition document.

Back to top

Sample Response #1

The example below shows the responses to the API request shown in Sample Request #1. In this example, the Swagger document is a customization of the sample Swagger Petstore API.

Sample response #1 headers

HTTP/1.1 200 OK
Date: Fri, 05 May 2017 00:54:14 GMT
Content-Type: application/json;charset=UTF-8

Sample response #1 body

{
  "swagger":"2.0",
  "info":{
    "title":"Swagger_Petstore_Subset",
    "description":"Swagger_Petstore_Subset",
    "version":"v1"
  },
  "host":"ubu1464qa-10.local.akana.com:7905",
  "basePath":"/api10087live",
  "schemes":[
    "http"
  ],
  "paths":{
    "/pet":{
      "post":{
        "tags":[
          "pet"
        ],
        "summary":"Add a new pet to the store",
        "operationId":"addPet",
        "consumes":[
          "application/json",
          "application/xml"
        ],
        "produces":[
          "application/xml",
          "application/json"
        ],
        "parameters":[
          {
            "in":"body",
            "name":"body",
            "description":"Pet object that needs to be added to the store",
            "required":true,
            "schema":{
              "$ref":"#/definitions/Pet"
            }
          }
        ],
        "responses":{
          "405":{
            "description":"Invalid input"
          }
        },
        "deprecated":false
      }
    },
    "/pet/{petId}":{
      "get":{
        "tags":[
          "pet"
        ],
        "summary":"Find pet by ID",
        "description":"Returns a single pet",
        "operationId":"getPetById",
        "produces":[
          "application/xml",
          "application/json"
        ],
        "parameters":[
          {
            "in":"path",
            "name":"petId",
            "description":"ID of pet to return",
            "type":"integer",
            "required":true
          }
        ],
        "responses":{
          "200":{
            "description":"successful operation",
            "schema":{
              "$ref":"#/definitions/Pet"
            }
          },
          "400":{
            "description":"Invalid ID supplied"
          },
          "404":{
            "description":"Pet not found"
          }
        },
        "deprecated":false
      },
      "delete":{
        "tags":[
          "pet"
        ],
        "summary":"Deletes a pet",
        "operationId":"deletePet",
        "produces":[
          "application/xml",
          "application/json"
        ],
        "parameters":[
          {
            "in":"path",
            "name":"petId",
            "description":"Pet id to delete",
            "type":"integer",
            "required":true
          },
          {
            "in":"header",
            "name":"api_key",
            "type":"string",
            "required":false
          }
        ],
        "responses":{
          "400":{
            "description":"Invalid ID supplied"
          },
          "404":{
            "description":"Pet not found"
          }
        },
        "deprecated":false
      }
    }
  },
  "definitions":{
    "Category":{
      "type":"object",
      "properties":{
        "id":{
          "type":"integer",
          "format":"int64"
        },
        "name":{
          "type":"string"
        }
      },
      "xml":{
        "name":"Category"
      }
    },
    "Tag":{
      "type":"object",
      "properties":{
        "id":{
          "type":"integer",
          "format":"int64"
        },
        "name":{
          "type":"string"
        }
      },
      "xml":{
        "name":"Tag"
      }
    },
    "Pet":{
      "type":"object",
      "required":[
        "name",
        "photoUrls"
      ],
      "properties":{
        "id":{
          "type":"integer",
          "format":"int64"
        },
        "category":{
          "$ref":"#/definitions/Category"
        },
        "name":{
          "type":"string",
          "example":"doggie"
        },
        "photoUrls":{
          "type":"array",
          "xml":{
            "name":"photoUrl",
            "wrapped":true
          },
          "items":{
            "type":"string"
          }
        },
        "tags":{
          "type":"array",
          "xml":{
            "name":"tag",
            "wrapped":true
          },
          "items":{
            "$ref":"#/definitions/Tag"
          }
        },
        "status":{
          "type":"string",
          "description":"pet status in the store",
          "enum":[
            "available",
            "pending",
            "sold"
          ]
        }
      },
      "xml":{
        "name":"Pet"
      }
    }
  }
}

Back to top

Sample Response #2

The examples below show the responses to the API requests shown in Sample Request #2. Click through to a specific example:

Response: Swagger 1.2

{
  "swaggerVersion":"1.2",
  "basePath":"http://{hostname}/prod",
  "apis":[
    {
      "path":"/pet",
      "operations":[
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"addPet",
          "method":"POST",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"Body",
              "paramType":"body"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        },
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"updatePet",
          "method":"PUT",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"Body",
              "paramType":"body"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        }
      ]
    },
    {
      "path":"/pet/{petId}",
      "operations":[
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"getPetById",
          "method":"GET",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"petId",
              "type":"string",
              "paramType":"path"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        }
      ]
    }
  ]
}

Response: Swagger 2.0

{
  "swaggerVersion":"1.2",
  "basePath":"http://{hostname}/prod",
  "apis":[
    {
      "path":"/pet",
      "operations":[
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"addPet",
          "method":"POST",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"Body",
              "paramType":"body"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        },
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"updatePet",
          "method":"PUT",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"Body",
              "paramType":"body"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        }
      ]
    },
    {
      "path":"/pet/{petId}",
      "operations":[
        {
          "consumes":[
            "*/*"
          ],
          "produces":[
            "*/*"
          ],
          "nickname":"getPetById",
          "method":"GET",
          "type":"void",
          "deprecated":false,
          "parameters":[
            {
              "name":"petId",
              "type":"string",
              "paramType":"path"
            }
          ],
          "responseMessages":[
            {
              "code":200
            }
          ]
        }
      ]
    }
  ]
}

Response: RAML 0.8

#%RAML 0.8
title: "__SwaggerAPI_Both_1.0_Production_Virtual"
baseUri: "http://{hostname}/prod"
protocols: [HTTP]
"/pet": 
  post: 
    body: 
      "*/*": 
    responses: 
      "200": 
        body: 
          "*/*": 
  put: 
    body: 
      "*/*": 
    responses: 
      "200": 
        body: 
          "*/*": 
"/pet/{petId}": 
  uriParameters: 
    "petId": 
      displayName: "petId"
      type: string
      required: false
      repeat: false
  get: 
    responses: 
      "200": 
        body: 
          "*/*": 
documentation: 
  - 
    title: "description"
    content: "First version"

Response: WADL

?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
  <doc>First version</doc>
  <grammars />
  <resources base="http://{hostname}/prod">
    <resource path="/pet">
      <method name="POST">
        <request>
          <param name="Body" type="xs:anyType" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
          <representation element="xs:anyType" mediaType="*/*" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
        </request>
        <response status="200">
          <representation element="xs:anyType" mediaType="*/*" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
        </response>
      </method>
      <method name="PUT">
        <request>
          <param name="Body" type="xs:anyType" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
          <representation element="xs:anyType" mediaType="*/*" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
        </request>
        <response status="200">
          <representation element="xs:anyType" mediaType="*/*" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
        </response>
      </method>
    </resource>
    <resource path="/pet/{petId}">
      <method name="GET">
        <request>
          <param name="petId" style="template" type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
          <representation mediaType="*/*" />
        </request>
        <response status="200">
          <representation element="xs:anyType" mediaType="*/*" xmlns:xs="http://www.w3.org/2001/XMLSchema" />
        </response>
      </method>
    </resource>
  </resources>
</application>

Response: WSDL

WSDL is generally used for SOAP rather than REST APIs. If you're retrieving the API definition in WSDL format for a REST API, it will include proprietary extensions for the Akana platform, as shown in the example below. In addition, depending on your browser, you might need to view source in the browser to see it. For SOAP services the response will be standard WSDL.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions targetNamespace="uri:acmepaymentscorp" xmlns="uri:acmepaymentscorp" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:atmo="uri:acmepaymentscorp" xmlns:tns="uri:acmepaymentscorp" xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:shttp="http://soa.com/wsdl/http" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <wsdl:message name="Request_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.Default_Operation">
    <wsdl:part name="path" type="xsd:string"></wsdl:part>
  </wsdl:message>
  <wsdl:message name="Response_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.Default_Operation">
    <wsdl:part name="Body" type="xsd:anyType"></wsdl:part>
  </wsdl:message>
  <wsdl:portType name="PortType_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production">
    <wsdl:operation name="Default_Operation">
      <wsdl:input message="Request_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.Default_Operation"></wsdl:input>
      <wsdl:output message="Response_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.Default_Operation"></wsdl:output>
    </wsdl:operation>
  </wsdl:portType>
  <wsdl:binding name="Binding_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.virtual" type="PortType_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production">
    <shttp:binding />
    <wsdl:operation name="Default_Operation">
      <shttp:operation faultSerialization="*/*" inputSerialization="*/*" location="/pet/{path:.+|}" method="GET" outputSerialization="*/*" />
      <wsdl:input>
        <shttp:input name="path" part="path" type="path" />
      </wsdl:input>
      <wsdl:output></wsdl:output>
    </wsdl:operation>
  </wsdl:binding>
  <wsdl:service name="svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.virtual">
    <wsdl:documentation>
      <sdoc:title xmlns:sdoc="http://soa.com/wsdl/doc">1AutoConnectApiName_version 1 _Production_Virtual</sdoc:title>
      <sdoc:description xmlns:sdoc="http://soa.com/wsdl/doc"><![CDATA[Api 1 Version]]></sdoc:description>
    </wsdl:documentation>
    <wsdl:port name="Binding_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.virtual_http" binding="Binding_svc_d411c74c-cb62-45b0-8963-474efcb42794.acmepaymentscorp.production.virtual">
      <shttp:address location="http://10.1.22.239:8901/apinotused" />
    </wsdl:port>
  </wsdl:service>
</wsdl:definitions>

Back to top

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header Description
Content-Type The Content-Type value is determined by the value specified in the Accept request header.

Back to top

Response Body

The response body is the generated API documentation.

Back to top

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item Value
401 Unauthorized. For example, you would get this response if you didn't include the custom X-Csrf-Token_{fedmemberID} header in the request, when it was required by the platform settings; or if you included an invalid or expired value for this header.
500 An error occurred processing the call.

More information about Akana API Platform API error messages.

Back to top

Related Topics