API Description Language Support

Information about the platform's support of API description languages for defining and managing REST APIs.

Note: For information about working with the API description document for a GraphQL API, see Viewing a GraphQL API in API Designer.

Table of Contents

Swagger support:

RAML support:

General/other:

Swagger Support:

What Swagger versions does the platform support?

The Akana Platform supports:

Note: Where a feature is supported in one or more API documentation formats but not others, converting to other formats is not supported. For example, conversion from OAS 3.0 to Swagger 2.0 might not be 100% because of differences in features supported by both specifications.

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.

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.

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

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

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

For more information about defining responses at the root level in OpenAPI 3.0 or Swagger, refer to the applicable section of the specification:

Are there any capabilities of the Swagger 2.0 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.

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

The platform currently has no support, or limited support, for the following capabilities of the YAML specification (https://yaml.org/spec/current.html):

The API platform does not recognize YAML anchor nodes as a reference to be used later. Similarly, the platform does not recognize YAML alias nodes and will treat the asterisk (*) indicator as a regular string, which will cause errors if a non-string item is expected.

For example, if a user attempts to upload a YAML API description document to the Community Manager developer portal, and the YAML includes the snippet below, it will cause an error, and upload will fail because the enum attribute of the property propertyTwo below expects an array and sees only the string ALIASTYPE.

  AliasType:
    type: string
    description: "AliasType"
    enum: &ALIASTYPE
      - string_one
      - string_two
 
  MyObject:
    type: object
    description: "MyObject"
    properties:
      propertyOne: 
        type: integer
        description: "property one"
      propertyTwo:
        type: string
        enum: *ALIASTYPE

Are there any capabilities of the OAS 3.x specification that the platform doesn't support?

The Akana API Platform does not support the following for OpenAPI version 3.1.

  • Viewing the OAS 3.1 documentation supporting all OAS 3.1 constructs.
  • Creating or updating the API using a graphical editor.
  • Webhook and Callback support.
  • Test client for OAS documentation and other OAS 3.1 constructs such as securitySchemes.

RAML Support:

What RAML versions does the platform support?

The Akana API platform supports the following RAML version:

  • 0.8

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 or WSDL.

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.

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.

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 2.0 but you want to view a RAML or OAS 3.0 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.

The example below shows the description language options for a REST-based API in version 2022.1.0 and later:

API description language options for a specific API: 2022.1.0 and later

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 these formats supported by the API Platform:

Note: For information about working with the API description document for a GraphQL API, see Viewing a GraphQL API in API Designer.

Download is not available for WADL.

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

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

Does the platform support SOAP?

Yes. The platform supports SOAP 1.1. You can create a SOAP-based API on the Community Manager 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 Community Manager 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?