Backend - Create Or Update

Creates or Updates a backend.

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

URI Parameters

Name In Required Type Description
backendId
path True

string

Identifier of the Backend entity. Must be unique in the current API Management service instance.

resourceGroupName
path True

string

The name of the resource group. The name is case insensitive.

serviceName
path True

string

The name of the API Management service.

Regex pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$

subscriptionId
path True

string

uuid

The ID of the target subscription. The value must be an UUID.

api-version
query True

string

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 Required Type Description
properties.protocol True

BackendProtocol

Backend communication protocol.

properties.url True

string

Runtime Url of the Backend.

properties.circuitBreaker

BackendCircuitBreaker

Backend Circuit Breaker Configuration

properties.credentials

BackendCredentialsContract

Backend Credentials Contract Properties

properties.description

string

Backend Description.

properties.pool

Pool

properties.properties

BackendProperties

Backend Properties contract

properties.proxy

BackendProxyContract

Backend gateway Contract Properties

properties.resourceId

string

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

Backend Title.

properties.tls

BackendTlsProperties

Backend TLS Properties

properties.type

BackendType

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

Responses

Name Type Description
200 OK

BackendContract

The existing backend was successfully updated.

Headers

ETag: string

201 Created

BackendContract

Backend was successfully created.

Headers

ETag: string

Other Status Codes

ErrorResponse

Error response describing why the operation failed.

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

ApiManagementCreateBackendProxyBackend
ApiManagementCreateBackendServiceFabric

ApiManagementCreateBackendProxyBackend

Sample request

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

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

Sample response

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

ApiManagementCreateBackendServiceFabric

Sample request

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

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

Sample response

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

Definitions

Name Description
BackendAuthorizationHeaderCredentials

Authorization header information.

BackendCircuitBreaker

The configuration of the backend circuit breaker

BackendContract

Backend details.

BackendCredentialsContract

Details of the Credentials used to connect to Backend.

BackendPoolItem

Backend pool service information

BackendProperties

Properties specific to the Backend Type.

BackendProtocol

Backend communication protocol.

BackendProxyContract

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

BackendServiceFabricClusterProperties

Properties of the Service Fabric Type Backend.

BackendTlsProperties

Properties controlling TLS Certificate Validation.

BackendType

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

CircuitBreakerFailureCondition

The trip conditions of the circuit breaker

CircuitBreakerRule

Rule configuration to trip the backend.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

FailureStatusCodeRange

The failure http status code range

Pool
X509CertificateName

Properties of server X509Names.

BackendAuthorizationHeaderCredentials

Authorization header information.

Name Type Description
parameter

string

Authentication Parameter value.

scheme

string

Authentication Scheme name.

BackendCircuitBreaker

The configuration of the backend circuit breaker

Name Type Description
rules

CircuitBreakerRule[]

The rules for tripping the backend.

BackendContract

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.circuitBreaker

BackendCircuitBreaker

Backend Circuit Breaker Configuration

properties.credentials

BackendCredentialsContract

Backend Credentials Contract Properties

properties.description

string

Backend Description.

properties.pool

Pool

properties.properties

BackendProperties

Backend Properties contract

properties.protocol

BackendProtocol

Backend communication protocol.

properties.proxy

BackendProxyContract

Backend gateway Contract Properties

properties.resourceId

string

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

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

Runtime Url of the Backend.

type

string

The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

BackendCredentialsContract

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.

BackendPoolItem

Backend pool service information

Name Type Description
id

string

The unique ARM id of the backend entity. The ARM id should refer to an already existing backend entity.

priority

integer

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

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

Properties specific to the Backend Type.

Name Type Description
serviceFabricCluster

BackendServiceFabricClusterProperties

Backend Service Fabric Cluster Properties

BackendProtocol

Backend communication protocol.

Name Type Description
http

string

The Backend is a RESTful service.

soap

string

The Backend is a SOAP service.

BackendProxyContract

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

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

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

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

BackendTlsProperties

Properties controlling TLS Certificate Validation.

Name Type Default value Description
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

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

Name Type Description
Pool

string

supports pool backend

Single

string

supports single backend

CircuitBreakerFailureCondition

The trip conditions of the circuit breaker

Name Type Description
count

integer

The threshold for opening the circuit.

errorReasons

string[]

The error reasons which are considered as failure.

interval

string

The interval during which the failures are counted.

percentage

integer

The threshold for opening the circuit.

statusCodeRanges

FailureStatusCodeRange[]

The status code ranges which are considered as failure.

CircuitBreakerRule

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.

name

string

The rule name.

tripDuration

string

The duration for which the circuit will be tripped.

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

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

Error response

Name Type Description
error

ErrorDetail

The error object.

FailureStatusCodeRange

The failure http status code range

Name Type Description
max

integer

The maximum http status code.

min

integer

The minimum http status code.

Pool

Name Type Description
services

BackendPoolItem[]

The list of backend entities belonging to a pool.

X509CertificateName

Properties of server X509Names.

Name Type Description
issuerCertificateThumbprint

string

Thumbprint for the Issuer of the Certificate.

name

string

Common Name of the Certificate.