API import restrictions and known issues
APPLIES TO: All API Management tiers
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.
- By default, converts the required query string parameters to required template parameters.
If you prefer that required query parameters in the specification are translated to query parameters in API Management, disable the Include query parameters in operation templates setting when creating the API in the portal. You can also accomplish this by using the APIs - Create or Update REST API to set the API's translateRequiredQueryParameters
property to query
.
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:
|
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. |
Azure Resource Manager API request size | When an OpenAPI document is provided via a URL to a location accessible from your API Management service. See Azure subscription limits. |
Supported extensions
The only supported extensions are:
Extension | Description |
---|---|
x-ms-paths |
|
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 aren't 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 aren't 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:
- OpenAPI 3.0.3
- OpenAPI 3.1.0 (import only)
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 is empty.
Supported
example
Unsupported
The following fields are included in either OpenAPI version 3.0.x or OpenAPI version 3.1.x, but aren't supported:
Object | Field |
---|---|
OpenAPI | externalDocs |
Info | summary |
Components |
|
PathItem |
|
Operation |
|
Parameter |
|
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 is 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 is generated by combining HTTP method and path template.- For example,
get-foo
.
- For example,
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 tooperationId
.
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}
is transformed intoget-foo-bar-buzz-quix-
.
- For example,
- Trim dashes on both sides.
- For example,
get-foo-bar-buzz-quix-
becomesget-foo-bar-buzz-quix
- For example,
- 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 are updated "in-place".
- If a match isn't found:
- A new operation is 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.
- A new operation is created by combining HTTP method and path template, for example,
All existing unmatched operations are 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}
is transformed intoget-foo-bar-buzz-quix-
.
- For example,
- Trim dashes on both sides.
- For example,
get-foo-bar-buzz-quix-
becomesget-foo-bar-buzz-quix
- For example,
- 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, it's:
- Azure resource name is exported as an
operationId
. - Display name is 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
, andxsd: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
, andxsd:include
dependencies in a WSDL file, see this GitHub repo.
WS-* specifications
WSDL files incorporating WS-* specifications aren't 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 aren't 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 aren't 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.
Multiple endpoints
WSDL files can define multiple services and endpoints (ports) by one or more wsdl:service
and wsdl:port
elements. However, the API Management gateway is able to import and proxy requests to only a single service and endpoint. If multiple services or endpoints are defined in the WSDL file, identify the target service name and endpoint when importing the API by using the wsdlSelector property.
Tip
If you want to load-balance requests across multiple services and endpoints, consider configuring a load-balanced backend pool.
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.