API import restrictions and known issues

When importing an API, you might encounter some restrictions or need to identify and rectify issues before you can successfully import. In this article, you'll learn:

  • API Management's behavior during OpenAPI import.
  • OpenAPI import limitations and how OpenAPI export works.
  • Requirements and limitations for WSDL and WADL import.

API Management during OpenAPI import

During OpenAPI import, API Management:

  • Checks specifically for query string parameters marked as required.
  • Converts the query string parameters to template parameters.

If you prefer a different behavior, you can either:

  • Manually change via form-based editor, or
  • Remove the "required" attribute from the OpenAPI definition, thus not converting them to template parameters.

For GET, HEAD, and OPTIONS operations, API Management discards a request body parameter if defined in the OpenAPI specification.

OpenAPI/Swagger import limitations

If you receive errors while importing your OpenAPI document, make sure you've validated it beforehand by either:

  • Using the designer in the Azure portal (Design > Front End > OpenAPI Specification Editor), or
  • With a third-party tool, such as Swagger Editor.

General

URL template requirements

Requirement Description
Unique names for required path and query parameters In OpenAPI:
  • A parameter name only needs to be unique within a location, for example path, query, header.
In API Management:
  • We allow operations to be discriminated by both path and query parameters.
  • OpenAPI doesn't support this discrimination, so we require parameter names to be unique within the entire URL template.
Defined URL parameter Must be part of the URL template.
Available source file URL Applied to relative server URLs.
\$ref pointers Can't reference external files.

OpenAPI specifications

Supported versions

API Management only supports:

  • OpenAPI version 2.
  • OpenAPI version 3.0.x (up to version 3.0.3).
  • OpenAPI version 3.1 (import only)

Size limitations

Size limit Description
Up to 4 MB When an OpenAPI specification is imported inline to API Management.
Size limit doesn't apply When an OpenAPI document is provided via a URL to a location accessible from your API Management service.

Supported extensions

The only supported extensions are:

Extension Description
x-ms-paths
  • Allows you to define paths that are differentiated by query parameters in the URL.
  • Covered in the AutoRest docs.
x-servers A backport of the OpenAPI 3 servers object for OpenAPI 2.

Unsupported extensions

Extension Description
Recursion API Management doesn't support definitions defined recursively.
For example, schemas referring to themselves.
Server object Not supported on the API operation level.
Produces keyword Describes MIME types returned by an API.
Not supported.

Custom extensions

  • Are ignored on import.
  • Aren't saved or preserved for export.

Unsupported definitions

Inline schema definitions for API operations aren't supported. Schema definitions:

  • Are defined in the API scope.
  • Can be referenced in API operations request or response scopes.

Ignored definitions

Security definitions are ignored.

Definition restrictions

When importing query parameters, only the default array serialization method (style: form, explode: true) is supported. For more details on query parameters in OpenAPI specifications, refer to the serialization specification.

Parameters defined in cookies are not supported. You can still use policy to decode and validate the contents of cookies.

OpenAPI version 2

OpenAPI version 2 support is limited to JSON format only.

"Form" type parameters are not supported. You can still use policy to decode and validate application/x-www-form-urlencoded and application/form-data payloads.

OpenAPI version 3.x

API Management supports the following specification versions:

HTTPS URLs

  • If multiple servers are specified, API Management will use the first HTTPS URL it finds.
  • If there aren't any HTTPS URLs, the server URL will be empty.

Supported

  • example

Unsupported

The following fields are included in OpenAPI version 3.0.x, but are not supported:

Object Field
OpenAPI externalDocs
Components
  • responses
  • parameters
  • examples
  • requestBodies
  • headers
  • securitySchemes
  • links
  • callbacks
PathItem
  • trace
  • servers
Operation
  • externalDocs
  • callbacks
  • security
  • servers
Parameter
  • allowEmptyValue
  • style
  • explode
  • allowReserved

OpenAPI import, update, and export mechanisms

General

API definitions exported from an API Management service are:

  • Primarily intended for external applications that need to call the API hosted in API Management service.
  • Not intended to be imported into the same or different API Management service.

For configuration management of API definitions across different services/environments, refer to documentation regarding using API Management service with Git.

Add new API via OpenAPI import

For each operation found in the OpenAPI document, a new operation will be created with:

  • Azure resource name set to operationId.

    • operationId value is normalized.
    • If operationId isn't specified (not present, null, or empty), Azure resource name value will be generated by combining HTTP method and path template.
      • For example, get-foo.
  • Display name set to summary.

    • summary value:
      • Imported as-is.
      • Length is limited to 300 characters.
    • If summary isn't specified (not present, null, or empty), display name value will set to operationId.

Normalization rules for operationId

  • Convert to lower case.
  • Replace each sequence of non-alphanumeric characters with a single dash.
    • For example, GET-/foo/{bar}?buzz={quix} will be transformed into get-foo-bar-buzz-quix-.
  • Trim dashes on both sides.
    • For example, get-foo-bar-buzz-quix- will become get-foo-bar-buzz-quix
  • Truncate to fit 76 characters, four characters less than maximum limit for a resource name.
  • Use remaining four characters for a de-duplication suffix, if necessary, in the form of -1, -2, ..., -999.

Update an existing API via OpenAPI import

During import, the existing API operation:

  • Changes to match the API described in the OpenAPI document.
  • Matches to an operation in the OpenAPI document by comparing its operationId value to the existing operation's Azure resource name.
    • If a match is found, existing operation’s properties will be updated "in-place".
    • If a match isn't found:
      • A new operation will be created by combining HTTP method and path template, for example, get-foo.
      • For each new operation, the import will attempt to copy policies from an existing operation with the same HTTP method and path template.

All existing unmatched operations will be deleted.

To make import more predictable, follow these guidelines:

  • Specify operationId property for every operation.
  • Refrain from changing operationId after initial import.
  • Never change operationId and HTTP method or path template at the same time.

Normalization rules for operationId

  • Convert to lower case.
  • Replace each sequence of non-alphanumeric characters with a single dash.
    • For example, GET-/foo/{bar}?buzz={quix} will be transformed into get-foo-bar-buzz-quix-.
  • Trim dashes on both sides.
    • For example, get-foo-bar-buzz-quix- will become get-foo-bar-buzz-quix
  • Truncate to fit 76 characters, four characters less than maximum limit for a resource name.
  • Use remaining four characters for a de-duplication suffix, if necessary, in the form of -1, -2, ..., -999.

Export API as OpenAPI

For each operation, its:

  • Azure resource name will be exported as an operationId.
  • Display name will be exported as a summary.

Note that normalization of the operationId is done on import, not on export.

WSDL

You can create SOAP pass-through and SOAP-to-REST APIs with WSDL files.

SOAP bindings

  • Only SOAP bindings of "document" and “literal” encoding style are supported.
  • No support for “rpc” style or SOAP-Encoding.

Imports and includes

  • The wsdl:import, xsd:import, and xsd:include directives aren't supported. Instead, merge the dependencies into one document.

  • For an open-source tool to resolve and merge wsdl:import, xsd:import, and xsd:include dependencies in a WSDL file, see this GitHub repo.

WS-* specifications

WSDL files incorporating WS-* specifications are not supported.

Messages with multiple parts

This message type is not supported.

WCF wsHttpBinding

  • SOAP services created with Windows Communication Foundation should use basicHttpBinding.
  • wsHttpBinding isn't supported.

MTOM

  • Services using MTOM may work.
  • Official support isn't offered at this time.

Recursion

  • Types defined recursively are not supported by API Management.
  • For example, refer to an array of themselves.

Multiple Namespaces

While multiple namespaces can be used in a schema, only the target namespace can be used to define message parts. These namespaces are used to define other input or output elements.

Namespaces other than the target are not preserved on export. While you can import a WSDL document defining message parts with other namespaces, all message parts will have the WSDL target namespace on export.

Arrays

SOAP-to-REST transformation supports only wrapped arrays shown in the example below:

    <complexType name="arrayTypeName">
        <sequence>
            <element name="arrayElementValue" type="arrayElementType" minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="typeName">
        <sequence>
            <element name="element1" type="someTypeName" minOccurs="1" maxOccurs="1"/>
            <element name="element2" type="someOtherTypeName" minOccurs="0" maxOccurs="1" nillable="true"/>
            <element name="arrayElement" type="arrayTypeName" minOccurs="1" maxOccurs="1"/>
        </sequence>
    </complexType>

WADL

Currently, there are no known WADL import issues.