Workspace Backend - Create Or Update

Reference

Service:: API Management

API Version:: 2024-05-01

Creates or Updates a backend.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/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.
workspaceId	path	True	string	Workspace identifier. Must be unique in the current API Management service instance. Regex pattern: `^[^*#&+:<>?]+$`
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.

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

ApiManagementCreateWorkspaceBackendProxyBackend

ApiManagementCreateWorkspaceBackendServiceFabric

ApiManagementCreateWorkspaceBackendProxyBackend

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/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

Status code:: 201

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/backends/proxybackend",
  "type": "Microsoft.ApiManagement/service/workspaces/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
    }
  }
}

Status code:: 200

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/backends/proxybackend",
  "type": "Microsoft.ApiManagement/service/workspaces/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
    }
  }
}

ApiManagementCreateWorkspaceBackendServiceFabric

Sample request

HTTP

PUT https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/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/workspaces/wks1/certificates/cert1",
        "serverX509Names": [
          {
            "name": "ServerCommonName1",
            "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
          }
        ],
        "maxPartitionResolutionRetries": 5
      }
    }
  }
}

Sample response

Status code:: 201

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/backends/sfbackend",
  "type": "Microsoft.ApiManagement/service/workspaces/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/workspaces/wks1/certificates/cert1",
        "serverX509Names": [
          {
            "name": "ServerCommonName1",
            "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
          }
        ],
        "maxPartitionResolutionRetries": 5
      }
    }
  }
}

Status code:: 200

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/workspaces/wks1/backends/sfbackend",
  "type": "Microsoft.ApiManagement/service/workspaces/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/workspaces/wks1/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.

Share via

Workspace Backend - Create Or Update

URI Parameters

Request Header

Request Body

Responses

Security

azure_auth

Scopes

Examples

ApiManagementCreateWorkspaceBackendProxyBackend

Sample request

Sample response

ApiManagementCreateWorkspaceBackendServiceFabric

Sample request

Sample response

Definitions

BackendAuthorizationHeaderCredentials

BackendCircuitBreaker

BackendContract

BackendCredentialsContract

BackendPoolItem

BackendProperties

BackendProtocol

BackendProxyContract

BackendServiceFabricClusterProperties

BackendTlsProperties

BackendType

CircuitBreakerFailureCondition

CircuitBreakerRule

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

FailureStatusCodeRange

Pool

X509CertificateName

Additional resources