API Description Language Support

Information about the platform's support of API description languages for API documentation.

API Platform Version: 8.1 and later

Table of Contents

Swagger support:
  1. What Swagger versions does the platform support?
  2. What Swagger support does the platform offer?
  3. Does the platform use any Swagger extensions?
  4. Does the platform support referencing of JSON schemas that are external to the API document definition?
  5. Does the platform support overloaded operations in API documentation?
  6. How does the platform support Swagger responses defined at the root level?
  7. Are there any capabilities of the Swagger specification that the platform doesn't support?
RAML support:
  1. What RAML versions does the platform support?
  2. What features of the RAML specification does the platform support?
  3. Does the platform support including sample values for generated RAML documentation?
  4. Does the platform support the capabilities of the RAML 200 Tutorial?
General/other:
  1. How can I view the API description document for an API?
  2. Does the platform support SOAP?

Swagger Support:

What Swagger versions does the platform support?

The Akana Platform supports:

The Akana API Platform user interface supports import of Swagger 2.0 and Swagger-YAML when adding a new API. However, it does not support upload of a Swagger 1.2 API description.

The underlying infrastructure supports creating an API by importing an API description document in either Swagger version, 1.2 or 2.0. You can use the Policy Manager console to load the Swagger 1.2 as a new service; then, you can use the Akana Platform user interface to add a new API and select the Publish an existing service as an API option.

Back to top

What Swagger support does the platform offer?

The platform allows defining an API by uploading a Swagger description document. It also supports updating an existing API by uploading a Swagger description document.

Aspects of the API definition, such as parameters, request and response model objects, responses including HTTP codes and messages, and descriptive content are all supported.

The API documentation is generated dynamically for users.

Back to top

Does the platform use any Swagger extensions?

Yes, the Akana API platform uses certain Swagger extensions to extend capabilities within the platform. These extensions are used internally and are not re-constituted when exporting an API description document.

In the underlying infrastructure, extensions are stored and reconstituted for the top-level Swagger object, operations, parameters, responses, and schema, regardless of whether the extension is external or internal.

Back to top

Does the platform support referencing of JSON schemas that are external to the API document definition?

No; all JSON schemas must be defined as part of the API description document, without the need for any additional external information. Referenced external schemas are not currently supported.

The platform supports referencing of JSON schemas in these scenarios:

  • Schemas referenced in the same RAML file
  • Inline schemas

Back to top

Does the platform support overloaded operations in API documentation?

The platform supports adding overloaded operations (multiple operations using the same path, with different design elements such as media types), and displays overloaded operations correctly in the user interface, including API pages, generated API documentation, and Test Client.

The Swagger 2.0 standard specification does not support overloaded operations; because of this, if you try to download a Swagger document (API > Details > Implementations (bottom of page) for an API that includes overloaded operations, the platform generates an error. This is also true for Swagger 1.2 and RAML. Overloaded operations are not an issue with WADL.

Back to top

How does the platform support Swagger responses defined at the root level?

In your Swagger document, you can define responses, including HTTP response codes, specific error messages, and so forth, in two ways:

  • Inline for each operation. The responses are visible in the API Designer for each operation.
  • within a responses section at the root level in the Swagger document. The operations reference the root-level responses section.

The example below defines three responses in the root-level responses section:

"responses": {
  "200": {
    "description": "The operation was successful",
    "schema": {
      "$ref": "#/definitions/Success"
    }
  },
  "401": {
    "description": "Authentication failed.",
    "schema": {
      "$ref": "#/definitions/AuthenticationError"
    }
  },
  "GeneralErrorInResponses": {
    "description": "Something went wrong.",
    "schema": {
      "$ref": "#/responses/GeneralErrorInResponses"
    }
  }
}

The example below shows how the Swagger definition for a specific operation might reference a response defined in the root-level responses section (first and third responses):

"paths": {
  "/test": {
    "get": {
      "responses": {
        "200": {
          "$ref": "#/responses/200"
        },
        "404": {
          "description": "Normal Inline Description"
        },
        "GeneralErrorInResponses": {
          "description": "GeneralErrorInResponses",
          "$ref": "#/responses/GeneralErrorInResponses"
        }
      }
    }
  }
},
How the plaform processes responses defined at the root level

The API Designer doesn't allow you to define responses at the root level. However, if they are defined in your imported Swagger document, the import process normalizes the Swagger response definitions, taking the content for each referenced response definition and placing it in the correct location in each operation that references it.

When you view the Swagger in the API Designer, you won't see the root responses section, but you'll see the applicable responses inline for each operation.

The API Designer includes a Responses section, but you can't add or modify the responses. See Responses section.

For more information about defining responses at the root level in Swagger, refer to the applicable section of the OpenAPI (Swagger) specification: Responses Definitions Object.

Back to top

Are there any capabilities of the Swagger specification that the platform doesn't support?

The platform currently has no support or limited support for these capabilities of the Swagger 2.0 specification (http://swagger.io/specification/):

  • Global Parameters

    The API Platform does not support the use of global parameters in Swagger 2.0, and neither does the underlying infrastructure.

  • Includes ($ref fields)

    In the API platform, includes are ignored, including references to schema documents.

    In the underlying infrastructure, upload is supported only for a single file. However, you can include referenced documents along with the root document by including multiple files in a single ZIP file (uploaded locally, or retrieved from an external URL).

  • Examples

    The Swagger 2.0 specification supports including sample values in Swagger documentation; however, the Akana API Platform doesn't currently support this feature.

    The underlying infrastructure supports including examples in Swagger for parameters, but not for operations. In the API platform, examples are ignored, and are not displayed in the API Designer or in generated documentation.

Back to top

RAML Support:

What RAML versions does the platform support?

The Akana API platform supports the following RAML version:

  • 0.8

Back to top

What features of the RAML specification does the platform support?

The Akana platform supports the core features of the RAML specification, as referenced in the RAML 100 Tutorial (http://raml.org/developers/raml-100-tutorial), except examples.

It supports:

  • Root
  • Resources
  • Methods
  • URI parameters
  • Query parameters
  • Responses

The platform doesn't yet support including examples in the generated documentation. Examples for query parameters, request body, or response body are not represented in the Akana API Designer and are omitted when exporting to Swagger, WSDL, or WADL

Back to top

Does the platform support including sample values for generated RAML documentation?

The RAML 0.8 specification support including a sample request in RAML documentation; however, the Akana API Platform currently does not support this feature.

The underlying infrastructure supports including examples for parameters in RAML, but not for operations.

Back to top

Does the platform support the capabilities of the RAML 200 Tutorial?

The RAML 200 tutorial (http://raml.org/developers/raml-200-tutorial) demonstrates more complex capabilities of RAML, including:

  • Body parameters
  • Form parameters

Includes: If you're uploading a single RAML file that has includes, either from a URL or from the local filesystem, the platform generates an error on import. However, you can include referenced documents along with the root document by including multiple files in a single ZIP file (uploaded locally, or retrieved from an external URL).

Some of the capabilities covered by the RAML 200 tutorial are not yet supported by the Akana API platform, including:

  • Traits: If you import a RAML file with Traits, the platform generates an error when trying to view the API in the API Designer.
  • RAML Specification Parameters: If you import a RAML file with Specification Parameters, no errors are generated but the Specification Parameters are ignored.
  • Resource Types: If you import a RAML file with Resource Types, the platform gives an error when trying to view the API in the API Designer.
  • External Schemas: the platform supports schemas referenced in the same RAML file and inline schemas, but does not support schemas referenced in an external file. The import fails.

Back to top

General/other:

How can I view the API description document for an API?

The API Admin can view the visual design of the API in API Designer, and can also view the Swagger representation by clicking the Swagger tab: see How do I view the Swagger representation of my API in API Designer?

If you're not the Admin for the API, or if you want to view the API description in some other format—for example, the API is based on Swagger but you want to view a RAML or WADL representation—you can do that in the Implementations section:

  • All users who have view access to the API: on the API's Overview page, in the Implementations section.
  • API Admins: The same information is also on the API's Details page.

In most cases, you can view a representation of the API in all supported description languages, as shown below:

API description language options for a specific API

Note: For SOAP-based APIs, created by uploading a WSDL file, only the WSDL option is available. See How do I add a SOAP-based API?

In the above example, the API can be viewed in all formats supported by the API Platform:

  • Swagger 2.0
  • RAML
  • Swagger 1.2
  • WADL
  • WSDL

To view the API representation, click the applicable icon. The API description is immediately available:

  • For Swagger 1.2, Swagger 2.0, and WSDL, the API description document opens in a new browser tab.
  • For RAML and WADL, the API description is available as a downloaded file.

Back to top

Does the platform support SOAP?

Yes. The platform supports SOAP 1.1. You can create a SOAP-based API on the developer portal by importing the WSDL file for the API. See How do I add a SOAP-based API?

If your API is SOAP-based, you can't modify it using the API Designer; however, you can update the API by uploading a new WSDL file.

In general, although the developer portal supports viewing the API description document for REST-based APIs in different formats, such as Swagger 2.0 or RAML, a SOAP-based API cannot be viewed in other API description formats. You can only view the WSDL. See How do I add a SOAP-based API?

Back to top