APIM REST-API for schemas broken above version 2021-08-01

Question

APIM REST-API for schemas broken above version 2021-08-01

Edwin van de Burgt 11

Version 2021-08-01 and before of the "Api Schema - List by Api" (https://learn.microsoft.com/en-us/rest/api/apimanagement/api-schema/list-by-api?view=rest-apimanagement-2021-08-01&tabs=HTTP) lists the schema's configured for the API. Versions above that, do not.

The documentation is inconsistent and the sample response does not match the real response for a lot of Api versions.

https://management.azure.com/subscriptions/{subscription}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{service}/apis/{api}/schemas?api-version=2021-08-01:

{
    "value": [
        {
            "id": "/subscriptions/.../resourceGroups/.../providers/Microsoft.ApiManagement/service/.../apis/.../schemas/apiSchemas",
            "type": "Microsoft.ApiManagement/service/apis/schemas",
            "name": "apiSchemas",
            "properties": {
                "contentType": "application/vnd.oai.openapi.components+json",
                "document": {
                    "components": {
                        "schemas": {
                            "createSomeObjectRequest": {
                                "properties": { ...

https://management.azure.com/subscriptions/{subscription}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{service}/apis/{api}/schemas?api-version=2024-05-01:

{
    "value": [
        {
            "id": "/subscriptions/.../resourceGroups/.../providers/Microsoft.ApiManagement/service/.../apis/.../schemas/apiSchemas",
            "type": "Microsoft.ApiManagement/service/apis/schemas",
            "name": "apiSchemas",
            "properties": {
                "contentType": "application/vnd.oai.openapi.components+json"
            }
        }
    ],
    "count": 1
}

Api's above version 2021-08-01 don't have the document node, hence provide no schema information.

0 comments

1 answer

Your answer

Answer 1

Hello Edwin !

Thank you for posting on MS Learn Q&A.

You can answer like this:

According to the current REST documentation for 2024-05-01, the List By Api operation still describes properties.document.components, properties.document.definitions and properties.document.value as part of the schema contract response. The sample response also shows document being returned. https://learn.microsoft.com/en-us/rest/api/apimanagement/api-schema/list-by-api?view=rest-apimanagement-2024-05-01

However, if the actual runtime response only returns:

"properties": {
  "contentType": "application/vnd.oai.openapi.components+json"
}

then the newer API version is not returning the schema payload even though the contract suggests it should.

A practical workaround is to use the Get Api schema endpoint per schema after listing the schema IDs:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}/schemas/{schemaId}?api-version=2024-05-01

So the recommended pattern would be to call List By Api to get schema IDs/names and for each schema you need to call Get Api Schema and if Get also omits document in 2024-05-01 then this should be raised as a product bug with Azure support.

Share via

APIM REST-API for schemas broken above version 2021-08-01

1 answer

Your answer