Backend - Create Or Update

Service:: API Management

API Version:: 2025-03-01-preview

Creates or Updates a backend.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/backends/{backendId}?api-version=2025-03-01-preview

URI Parameters

Name	In	Required	Type	Description
backendId	path	True	string minLength: 1 maxLength: 80	Identifier of the Backend entity. Must be unique in the current API Management service instance.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
serviceName	path	True	string minLength: 1 maxLength: 50 pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$	The name of the API Management service.
subscriptionId	path	True	string minLength: 1	The ID of the target subscription.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Header

Name	Required	Type	Description
If-Match		string	ETag of the Entity. Not required when creating an entity, but required when updating an entity.

Request Body

Name	Type	Description
properties.azureRegion	string	Azure region in which the backend is deployed. Can be optionally specified to use features such as carbon-optimized load balancer.
properties.circuitBreaker	BackendCircuitBreaker	Backend Circuit Breaker Configuration
properties.credentials	BackendCredentialsContract	Backend Credentials Contract Properties
properties.description	string minLength: 1 maxLength: 2000	Backend Description.
properties.pool	BackendBaseParametersPool	Backend Pool Properties
properties.properties	BackendProperties	Backend Properties contract
properties.protocol	BackendProtocol	Backend communication protocol. Required when backend type is 'Single'.
properties.proxy	BackendProxyContract	Backend gateway Contract Properties
properties.resourceId	string minLength: 1 maxLength: 2000	Management Uri of the Resource in External System. This URL can be the Arm Resource Id of Logic Apps, Function Apps or API Apps.
properties.title	string minLength: 1 maxLength: 300	Backend Title.
properties.tls	BackendTlsProperties	Backend TLS Properties
properties.type	BackendType	Type of the backend. A backend can be either Single or Pool.
properties.url	string minLength: 1 maxLength: 2000	Runtime Url of the Backend. Required when backend type is 'Single'.

Responses

Name	Type	Description
200 OK	BackendContract	The request has succeeded. Headers ETag: string
201 Created	BackendContract	The request has succeeded and a new resource has been created as a result. Headers ETag: string Retry-After: integer
Other Status Codes	ErrorResponse	An unexpected error response.

Name

Type

Description

200 OK

BackendContract

The request has succeeded.

Headers

ETag: string

201 Created

BackendContract

The request has succeeded and a new resource has been created as a result.

Headers

ETag: string
Retry-After: integer

Other Status Codes

ErrorResponse

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

ApiManagementCreateBackendCustomAssignedCertificateThumbprint

ApiManagementCreateBackendCustomAssignedCertificateX509Names

ApiManagementCreateBackendProxyBackend

ApiManagementCreateBackendServiceFabric

ApiManagementCreateBackendWithAzureRegion

ApiManagementCreateBackendWithCarbonAwareLoadBalancer

ApiManagementCreateBackendWithPriorityBasedLoadBalancer

ApiManagementCreateBackendWithSimpleLoadBalancer

ApiManagementCreateBackendWithWeightedLoadBalancer

ApiManagementCreateBackendCustomAssignedCertificateThumbprint

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend?api-version=2025-03-01-preview

{
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverCertificateThumbprints": [
        "1365083bae61ee876fc26850b825d05d3eb2e503"
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

Sample response

Status code:: 200

{
  "name": "cabackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend",
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverCertificateThumbprints": [
        "1365083bae61ee876fc26850b825d05d3eb2e503"
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

Status code:: 201

{
  "name": "cabackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend",
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverCertificateThumbprints": [
        "1365083bae61ee876fc26850b825d05d3eb2e503"
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

ApiManagementCreateBackendCustomAssignedCertificateX509Names

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend?api-version=2025-03-01-preview

{
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverX509Names": [
        {
          "name": "*.badssl.com",
          "issuerCertificateThumbprint": null
        }
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

Sample response

Status code:: 200

{
  "name": "cabackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend",
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverX509Names": [
        {
          "name": "*.badssl.com",
          "issuerCertificateThumbprint": null
        }
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

Status code:: 201

{
  "name": "cabackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/cabackend",
  "properties": {
    "description": "Custom Assigned certificate Example",
    "tls": {
      "serverX509Names": [
        {
          "name": "*.badssl.com",
          "issuerCertificateThumbprint": null
        }
      ],
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://self-signed.badssl.com/",
    "protocol": "http"
  }
}

ApiManagementCreateBackendProxyBackend

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend?api-version=2025-03-01-preview

{
  "properties": {
    "description": "description5308",
    "credentials": {
      "authorization": {
        "parameter": "opensesma",
        "scheme": "Basic"
      },
      "header": {
        "x-my-1": [
          "val1",
          "val2"
        ]
      },
      "query": {
        "sv": [
          "xx",
          "bb",
          "cc"
        ]
      }
    },
    "proxy": {
      "password": "<password>",
      "url": "http://192.168.1.1:8080",
      "username": "Contoso\\admin"
    },
    "tls": {
      "validateCertificateChain": true,
      "validateCertificateName": true
    },
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

Sample response

Status code:: 200

{
  "name": "proxybackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
  "properties": {
    "description": "description5308",
    "credentials": {
      "authorization": {
        "parameter": "opensesma",
        "scheme": "Basic"
      },
      "header": {
        "x-my-1": [
          "val1",
          "val2"
        ]
      },
      "query": {
        "sv": [
          "xx",
          "bb",
          "cc"
        ]
      }
    },
    "proxy": {
      "password": "<password>",
      "url": "http://192.168.1.1:8080",
      "username": "Contoso\\admin"
    },
    "tls": {
      "validateCertificateChain": false,
      "validateCertificateName": false
    },
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

Status code:: 201

{
  "name": "proxybackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
  "properties": {
    "description": "description5308",
    "credentials": {
      "authorization": {
        "parameter": "opensesma",
        "scheme": "Basic"
      },
      "header": {
        "x-my-1": [
          "val1",
          "val2"
        ]
      },
      "query": {
        "sv": [
          "xx",
          "bb",
          "cc"
        ]
      }
    },
    "proxy": {
      "password": "<password>",
      "url": "http://192.168.1.1:8080",
      "username": "Contoso\\admin"
    },
    "tls": {
      "validateCertificateChain": false,
      "validateCertificateName": false
    },
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

ApiManagementCreateBackendServiceFabric

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sfbackend?api-version=2025-03-01-preview

{
  "properties": {
    "description": "Service Fabric Test App 1",
    "properties": {
      "serviceFabricCluster": {
        "clientCertificateId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/certificates/cert1",
        "managementEndpoints": [
          "https://somecluster.com"
        ],
        "maxPartitionResolutionRetries": 5,
        "serverX509Names": [
          {
            "name": "ServerCommonName1",
            "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
          }
        ]
      }
    },
    "url": "fabric:/mytestapp/mytestservice",
    "protocol": "http"
  }
}

Sample response

Status code:: 200

{
  "name": "sfbackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sfbackend",
  "properties": {
    "description": "Service Fabric Test App 1",
    "properties": {
      "serviceFabricCluster": {
        "clientCertificateId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/certificates/cert1",
        "managementEndpoints": [
          "https://somecluster.com"
        ],
        "maxPartitionResolutionRetries": 5,
        "serverX509Names": [
          {
            "name": "ServerCommonName1",
            "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
          }
        ]
      }
    },
    "url": "fabric:/mytestapp/mytestservice",
    "protocol": "http"
  }
}

Status code:: 201

{
  "name": "sfbackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sfbackend",
  "properties": {
    "description": "Service Fabric Test App 1",
    "properties": {
      "serviceFabricCluster": {
        "clientCertificateId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/certificates/cert1",
        "managementEndpoints": [
          "https://somecluster.com"
        ],
        "maxPartitionResolutionRetries": 5,
        "serverX509Names": [
          {
            "name": "ServerCommonName1",
            "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
          }
        ]
      }
    },
    "url": "fabric:/mytestapp/mytestservice",
    "protocol": "http"
  }
}

ApiManagementCreateBackendWithAzureRegion

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/azurebackend?api-version=2025-03-01-preview

{
  "properties": {
    "azureRegion": "northeurope",
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

Sample response

Status code:: 200

{
  "name": "azurebackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/azurebackend",
  "properties": {
    "azureRegion": "northeurope",
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

Status code:: 201

{
  "name": "azurebackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/azurebackend",
  "properties": {
    "azureRegion": "northeurope",
    "url": "https://backendname2644/",
    "protocol": "http"
  }
}

ApiManagementCreateBackendWithCarbonAwareLoadBalancer

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/carbonawareloadbalancerbackend?api-version=2025-03-01-preview

{
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sustainable-backend-europe-north",
          "preferredCarbonEmission": "Medium",
          "priority": 1,
          "weight": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
          "priority": 1,
          "weight": 1
        }
      ]
    }
  }
}

Sample response

Status code:: 200

{
  "name": "carbonawareloadbalancerbackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/carbonawareloadbalancerbackend",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sustainable-backend-europe-north",
          "preferredCarbonEmission": "Medium",
          "priority": 1,
          "weight": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
          "priority": 1,
          "weight": 1
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

Status code:: 201

{
  "name": "carbonawareloadbalancerbackend",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/carbonawareloadbalancerbackend",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sustainable-backend-europe-north",
          "preferredCarbonEmission": "Medium",
          "priority": 1,
          "weight": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
          "priority": 1,
          "weight": 1
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

ApiManagementCreateBackendWithPriorityBasedLoadBalancer

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/priority-based-load-balancer?api-version=2025-03-01-preview

{
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-3",
          "priority": 2
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-4",
          "priority": 2
        }
      ]
    }
  }
}

Sample response

Status code:: 200

{
  "name": "priority-based-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/priority-based-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-3",
          "priority": 2
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-4",
          "priority": 2
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

Status code:: 201

{
  "name": "priority-based-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/priority-based-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "priority": 1
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-3",
          "priority": 2
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-4",
          "priority": 2
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

ApiManagementCreateBackendWithSimpleLoadBalancer

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/simple-load-balancer?api-version=2025-03-01-preview

{
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1"
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2"
        }
      ]
    }
  }
}

Sample response

Status code:: 200

{
  "name": "simple-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/simple-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1"
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2"
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

Status code:: 201

{
  "name": "simple-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/simple-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1"
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2"
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

ApiManagementCreateBackendWithWeightedLoadBalancer

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/weighted-load-balancer?api-version=2025-03-01-preview

{
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "weight": 75
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "weight": 25
        }
      ]
    }
  }
}

Sample response

Status code:: 200

{
  "name": "weighted-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/weighted-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "weight": 75
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "weight": 25
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

Status code:: 201

{
  "name": "weighted-load-balancer",
  "type": "Microsoft.ApiManagement/service/backends",
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/weighted-load-balancer",
  "properties": {
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-1",
          "weight": 75
        },
        {
          "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/backend-2",
          "weight": 25
        }
      ]
    },
    "title": null,
    "url": null,
    "protocol": null
  }
}

Definitions

Name	Description
Backend-sessionId-source	Source from where the session id is extracted.
BackendAuthorizationHeaderCredentials	Authorization header information.
BackendBaseParametersPool
BackendCircuitBreaker	The configuration of the backend circuit breaker
BackendContract	Backend details.
BackendCredentialsContract	Details of the Credentials used to connect to Backend.
BackendFailureResponse	The response to be returned when a backend fails to respond
BackendPoolItem	Backend pool service information
BackendProperties	Properties specific to the Backend Type.
BackendProtocol	Backend communication protocol. Required when backend type is 'Single'.
BackendProxyContract	Details of the Backend WebProxy Server to use in the Request to Backend.
BackendServiceFabricClusterProperties	Properties of the Service Fabric Type Backend.
BackendSessionAffinity	The session stickiness properties of the backend pool.
BackendSessionId	The properties of the id that identifies the requests belonging to the same session.
BackendTlsProperties	Properties controlling TLS Certificate Validation.
BackendType	Type of the backend. A backend can be either Single or Pool.
CarbonEmissionCategory	Scope 2 carbon emission preference for the backend. When specified, the load balancer will optimize traffic flow by routing to regions that have carbon emission less than or equal to the specified category. However, when all other backends are not available it will route traffic to these regions anyway. This requires the backend to be attributed with 'azureRegion' information.
CircuitBreakerFailureCondition	The trip conditions of the circuit breaker
CircuitBreakerRule	Rule configuration to trip the backend.
createdByType	The type of identity that created the resource.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
FailureStatusCodeRange	The failure http status code range
systemData	Metadata pertaining to creation and last modification of the resource.
X509CertificateName	Properties of server X509Names.

Backend-sessionId-source

Enumeration

Source from where the session id is extracted.

Value	Description
cookie	The session id is set by APIM gateway in a cookie and is extracted from the cookies in client requests.

BackendAuthorizationHeaderCredentials

Object

Authorization header information.

Name	Type	Description
parameter	string minLength: 1 maxLength: 300	Authentication Parameter value.
scheme	string minLength: 1 maxLength: 100	Authentication Scheme name.

BackendBaseParametersPool

Object

Name	Type	Description
failureResponse	BackendFailureResponse	The response to be returned when all the backends in the pool are inactive.
services	BackendPoolItem[]	The list of backend entities belonging to a pool.
sessionAffinity	BackendSessionAffinity	The session stickiness properties of the backend pool.

BackendCircuitBreaker

Object

The configuration of the backend circuit breaker

Name	Type	Description
rules	CircuitBreakerRule[]	The rules for tripping the backend.

BackendContract

Object

Backend details.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	The name of the resource
properties.azureRegion	string	Azure region in which the backend is deployed. Can be optionally specified to use features such as carbon-optimized load balancer.
properties.circuitBreaker	BackendCircuitBreaker	Backend Circuit Breaker Configuration
properties.credentials	BackendCredentialsContract	Backend Credentials Contract Properties
properties.description	string minLength: 1 maxLength: 2000	Backend Description.
properties.pool	BackendBaseParametersPool	Backend Pool Properties
properties.properties	BackendProperties	Backend Properties contract
properties.protocol	BackendProtocol	Backend communication protocol. Required when backend type is 'Single'.
properties.proxy	BackendProxyContract	Backend gateway Contract Properties
properties.resourceId	string minLength: 1 maxLength: 2000	Management Uri of the Resource in External System. This URL can be the Arm Resource Id of Logic Apps, Function Apps or API Apps.
properties.title	string minLength: 1 maxLength: 300	Backend Title.
properties.tls	BackendTlsProperties	Backend TLS Properties
properties.type	BackendType	Type of the backend. A backend can be either Single or Pool.
properties.url	string minLength: 1 maxLength: 2000	Runtime Url of the Backend. Required when backend type is 'Single'.
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

BackendCredentialsContract

Object

Details of the Credentials used to connect to Backend.

Name	Type	Description
authorization	BackendAuthorizationHeaderCredentials	Authorization header authentication
certificate	string[]	List of Client Certificate Thumbprints. Will be ignored if certificatesIds are provided.
certificateIds	string[]	List of Client Certificate Ids.
header	object	Header Parameter description.
query	object	Query Parameter description.

BackendFailureResponse

Object

The response to be returned when a backend fails to respond

Name	Type	Description
statusCode	integer (int32) minimum: 100 maximum: 599	The status code of the response.

BackendPoolItem

Object

Backend pool service information

Name	Type	Description
id	string (arm-id)	The unique ARM id of the backend entity. The ARM id should refer to an already existing backend entity.
preferredCarbonEmission	CarbonEmissionCategory	Scope 2 carbon emission preference for the backend. When specified, the load balancer will optimize traffic flow by routing to regions that have carbon emission less than or equal to the specified category. However, when all other backends are not available it will route traffic to these regions anyway. This requires the backend to be attributed with 'azureRegion' information.
priority	integer (int32) minimum: 0 maximum: 100	The priority of the backend entity in the backend pool. Must be between 0 and 100. It can be also null if the value not specified.
weight	integer (int32) minimum: 0 maximum: 100	The weight of the backend entity in the backend pool. Must be between 0 and 100. It can be also null if the value not specified.

BackendProperties

Object

Properties specific to the Backend Type.

Name	Type	Description
serviceFabricCluster	BackendServiceFabricClusterProperties	Backend Service Fabric Cluster Properties

BackendProtocol

Enumeration

Backend communication protocol. Required when backend type is 'Single'.

Value	Description
http	The Backend is a RESTful service.
soap	The Backend is a SOAP service.

BackendProxyContract

Object

Details of the Backend WebProxy Server to use in the Request to Backend.

Name	Type	Description
password	string	Password to connect to the WebProxy Server
url	string minLength: 1 maxLength: 2000	WebProxy Server AbsoluteUri property which includes the entire URI stored in the Uri instance, including all fragments and query strings.
username	string	Username to connect to the WebProxy server

BackendServiceFabricClusterProperties

Object

Properties of the Service Fabric Type Backend.

Name	Type	Description
clientCertificateId	string	The client certificate id for the management endpoint.
clientCertificatethumbprint	string	The client certificate thumbprint for the management endpoint. Will be ignored if certificatesIds are provided
managementEndpoints	string[]	The cluster management endpoint.
maxPartitionResolutionRetries	integer (int32)	Maximum number of retries while attempting resolve the partition.
serverCertificateThumbprints	string[]	Thumbprints of certificates cluster management service uses for tls communication
serverX509Names	X509CertificateName[]	Server X509 Certificate Names Collection

BackendSessionAffinity

Object

The session stickiness properties of the backend pool.

Name	Type	Description
sessionId	BackendSessionId	The id that identifies the requests belonging to the same session.

BackendSessionId

Object

The properties of the id that identifies the requests belonging to the same session.

Name	Type	Description
name	string	Name of the variable that refers to the session id.
source	Backend-sessionId-source	Source from where the session id is extracted.

BackendTlsProperties

Object

Properties controlling TLS Certificate Validation.

Name	Type	Default value	Description
serverCertificateThumbprints	string[]		Thumbprints of certificates used by the backend host for TLS communication.
serverX509Names	X509CertificateName[]		Server X509 Certificate Names of the Backend Host.
validateCertificateChain	boolean	True	Flag indicating whether SSL certificate chain validation should be done when using self-signed certificates for this backend host.
validateCertificateName	boolean	True	Flag indicating whether SSL certificate name validation should be done when using self-signed certificates for this backend host.

BackendType

Enumeration

Type of the backend. A backend can be either Single or Pool.

Value	Description
Single	supports single backend
Pool	supports pool backend

CarbonEmissionCategory

Enumeration

Scope 2 carbon emission preference for the backend. When specified, the load balancer will optimize traffic flow by routing to regions that have carbon emission less than or equal to the specified category. However, when all other backends are not available it will route traffic to these regions anyway. This requires the backend to be attributed with 'azureRegion' information.

Value	Description
VeryLow	Carbon intensity of less than or equal to 150 grams CO₂e per KWh
Low	Carbon intensity between 151 & 300 (incl) grams CO₂e per KWh
Medium	Carbon intensity between 301 & 500 (incl) grams CO₂e per KWh
High	Carbon intensity between 501 & 700 (incl) grams CO₂e per KWh
VeryHigh	Carbon intensity of more than 700 grams CO₂e per KWh

CircuitBreakerFailureCondition

Object

The trip conditions of the circuit breaker

Name	Type	Description
count	integer (int64)	The threshold for opening the circuit.
errorReasons	string[]	The error reasons which are considered as failure.
interval	string (duration)	The interval during which the failures are counted.
percentage	integer (int64)	The threshold for opening the circuit.
statusCodeRanges	FailureStatusCodeRange[]	The status code ranges which are considered as failure.

CircuitBreakerRule

Object

Rule configuration to trip the backend.

Name	Type	Description
acceptRetryAfter	boolean	flag to accept Retry-After header from the backend.
failureCondition	CircuitBreakerFailureCondition	The conditions for tripping the circuit breaker.
failureResponse	BackendFailureResponse	The response of the backend when the circuit breaker gets open.
name	string	The rule name.
tripDuration	string (duration)	The duration for which the circuit will be tripped.

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

FailureStatusCodeRange

Object

The failure http status code range

Name	Type	Description
max	integer (int32) minimum: 200 maximum: 599	The maximum http status code.
min	integer (int32) minimum: 200 maximum: 599	The minimum http status code.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

X509CertificateName

Object

Properties of server X509Names.

Name	Type	Description
issuerCertificateThumbprint	string	Thumbprint for the Issuer of the Certificate.
name	string	Common Name of the Certificate.

Share via

Backend - Create Or Update

URI Parameters

Request Header

Request Body

Responses

Security

azure_auth

Scopes

Examples

ApiManagementCreateBackendCustomAssignedCertificateThumbprint

Sample request

Sample response

ApiManagementCreateBackendCustomAssignedCertificateX509Names

Sample request

Sample response

ApiManagementCreateBackendProxyBackend

Sample request

Sample response

ApiManagementCreateBackendServiceFabric

Sample request

Sample response

ApiManagementCreateBackendWithAzureRegion

Sample request

Sample response

ApiManagementCreateBackendWithCarbonAwareLoadBalancer

Sample request

Sample response

ApiManagementCreateBackendWithPriorityBasedLoadBalancer

Sample request

Sample response

ApiManagementCreateBackendWithSimpleLoadBalancer

Sample request

Sample response

ApiManagementCreateBackendWithWeightedLoadBalancer

Sample request

Sample response

Definitions

Backend-sessionId-source

BackendAuthorizationHeaderCredentials

BackendBaseParametersPool

BackendCircuitBreaker

BackendContract

BackendCredentialsContract

BackendFailureResponse

BackendPoolItem

BackendProperties

BackendProtocol

BackendProxyContract

BackendServiceFabricClusterProperties

BackendSessionAffinity

BackendSessionId

BackendTlsProperties

BackendType

CarbonEmissionCategory

CircuitBreakerFailureCondition

CircuitBreakerRule

createdByType

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

FailureStatusCodeRange

systemData

X509CertificateName