Issue with OpenAPI file import in APIM

Question

Hi,

I'm trying to create an API by importing an OpenAPI yaml file, already validated with https://editor.swagger.io/ but I'm received the following errors:

Code: ValidationError

    *Message: URL template is invalid*

    *Target: value[8].urlTemplate    (ValidationError) URL template is invalid*

    *Code: ValidationError*

    *Message: URL template is invalid*

    *Target: value[9].urlTemplate    (ValidationError) URL template is invalid*

    *Code: ValidationError*

    *Message: URL template is invalid*

    *Target: value[10].urlTemplate   (ValidationError) URL template is invalid*

    *Code: ValidationError*

    *Message: URL template is invalid*

    *Target: value[11].urlTemplate   (ValidationError) All template parameters used in the UriTemplate must be defined in the Operation 'Container_SetMetadata', and vice-versa.*

    *Code: ValidationError*

    *Message: All template parameters used in the UriTemplate must be defined in the Operation 'Container_SetMetadata', and vice-versa.*

    *Target: value[11]       (ValidationError) URL template is invalid*

It seems additional requirements are checked for other the ones required by OpenAPI standard. Please see the here attached OpenAPI file I'm using: blob_openapi.yaml.txt

This is the az cli command I've ran:

APIMServiceName="My_APIM_Resopurce"

ResourceGroupName="My_Resource_Group"

APIId="azure-blob-storage"

APIPath="blob"

SpecificationFormat="OpenApi"

SpecificationPath="blob_openapi.yaml"

az apim api import --path $APIPath --resource-group $ResourceGroupName --service-name $APIMServiceName --api-id $APIId --specification-format $SpecificationFormat --specification-path $SpecificationPath

Thanks

Antonio

Answer 1

Hi Antonio,

Thank you for reaching out. The errors indicate URL template validation issues in your OpenAPI file. Azure API Management has specific requirements for URL templates and parameter definitions.

For guidance, please refer to Microsoft’s official documentation:

Import an OpenAPI specification

API Management policies for URL handling

Ensure all template parameters in your paths are explicitly defined in the corresponding operations.

Best regards,
Alex
PS If my answer help to you, please Accept my answer.
PPS that is my answer and it is not a comment :)

Answer 2

Hi @SALOMONE ANTONIO

After analyzing both the Azure Blob Storage OpenAPI YAML file you provided and the Swagger Petstore specification from Swagger.io, I trace the ValidationError: URL template is invalid issue you encountered when importing the Blob API spec into Azure API Management (APIM).

The Swagger Petstore OpenAPI specification is well-structured and imports cleanly into APIM because it strictly follows OpenAPI standards and APIM import requirements, particularly around path parameters.

for example:

/pet/{petId}:
  get:
    parameters:
      - name: petId
        in: path
        required: true
        schema:
          type: integer

Here, the {petId} in the path is explicitly declared as a path parameter with required: true, exactly what APIM expects.

Blob Storage YAML Triggers APIM Validation Errors: -

In contrast, the Azure Blob Storage spec defines paths like:

"/{containerName}?restype=container&comp=metadata":

But the operations under these paths do not explicitly define {containerName} as a path parameter. Instead, they refer to a shared component parameter like:

- $ref: "#/components/parameters/ContainerName"

And that component is defined with:

in: query

This is invalid for APIM when {containerName} is clearly a path segment. APIM requires that any template parameter in the path (wrapped in {}) must be: - Defined in every operation that uses it, declared with in: path, Marked as required: true

To resolve the issue, update all operations that reference {containerName}, {blobName}, etc., to include the following directly or via corrected $ref

parameters:
  - name: containerName
    in: path
    required: true
    schema:
      type: string

Or, update the referenced ContainerName component to:

components:
  parameters:
    ContainerName:
      name: containerName
      in: path
      required: true
      schema:
        type: string

Repeat this for any other path parameters used in the URL templates.

Each template parameter in the URI must be defined in the OpenAPI operation’s parameter list as a required path parameter.

After making these adjustments, try importing the API again into APIM using the Azure CLI command:

az apim api import --resource-group My_Resource_Group --service-name My_APIM_Resource --api-id azure-blob-storage --path blob --specification-format OpenApi --specification-path blob_openapi.yaml

For more details, please refer the following Microsoft documentation: Import restrictions for OpenAPI in APIM, Common import validation errors, OpenAPI Import Guidelines.

Hope it helps!

---

Please do not forget to click "Accept the answer” and Yes wherever the information provided helps you, this can be beneficial to other community members.

If you have any other questions or still running into more issues, let me know in the "comments" and I would be happy to help you.