API Management transformation policies

• 03/11/2019
• 17 minutes to read
• • 
  • 
  • 
  • 
  • 
  • +8

This topic provides a reference for the following API Management policies. For information on adding and configuring policies, see Policies in API Management.

Transformation policies

• Convert JSON to XML - Converts request or response body from JSON to XML.

• Convert XML to JSON - Converts request or response body from XML to JSON.

• Find and replace string in body - Finds a request or response substring and replaces it with a different substring.

• Mask URLs in content - Re-writes (masks) links in the response body so that they point to the equivalent link via the gateway.

• Set backend service - Changes the backend service for an incoming request.

• Set body - Sets the message body for incoming and outgoing requests.

• Set HTTP header - Assigns a value to an existing response and/or request header or adds a new response and/or request header.

• Set query string parameter - Adds, replaces value of, or deletes request query string parameter.

• Rewrite URL - Converts a request URL from its public form to the form expected by the web service.

• Transform XML using an XSLT - Applies an XSL transformation to XML in the request or response body.

Convert JSON to XML

The json-to-xml policy converts a request or response body from JSON to XML.

Policy statement

<json-to-xml apply="always | content-type-json" consider-accept-header="true | false" parse-date="true | false"/>

Example

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false"/>
    </outbound>
</policies>

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound, on-error

• Policy scopes: all scopes

Convert XML to JSON

The xml-to-json policy converts a request or response body from XML to JSON. This policy can be used to modernize APIs based on XML-only backend web services.

Policy statement

<xml-to-json kind="javascript-friendly | direct" apply="always | content-type-xml" consider-accept-header="true | false"/>

Example

<policies>
    <inbound>
        <base />
    </inbound>
    <outbound>
        <base />
        <xml-to-json kind="direct" apply="always" consider-accept-header="false" />
    </outbound>
</policies>

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound, on-error

• Policy scopes: all scopes

Find and replace string in body

The find-and-replace policy finds a request or response substring and replaces it with a different substring.

Policy statement

<find-and-replace from="what to replace" to="replacement" />

Example

<find-and-replace from="notebook" to="laptop" />

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound, backend, on-error

• Policy scopes: all scopes

Mask URLs in content

The redirect-content-urls policy re-writes (masks) links in the response body so that they point to the equivalent link via the gateway. Use in the outbound section to re-write response body links to make them point to the gateway. Use in the inbound section for an opposite effect.

Policy statement

<redirect-content-urls />

Example

<redirect-content-urls />

Elements

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound

• Policy scopes: all scopes

Set backend service

Use the set-backend-service policy to redirect an incoming request to a different backend than the one specified in the API settings for that operation. This policy changes the backend service base URL of the incoming request to the one specified in the policy.

Policy statement

<set-backend-service base-url="base URL of the backend service" />

or

<set-backend-service backend-id="identifier of the backend entity specifying base URL of the backend service" />

Example

<policies>
    <inbound>
        <choose>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2013-05")">
                <set-backend-service base-url="http://contoso.com/api/8.2/" />
            </when>
            <when condition="@(context.Request.Url.Query.GetValueOrDefault("version") == "2014-03")">
                <set-backend-service base-url="http://contoso.com/api/9.1/" />
            </when>
        </choose>
        <base />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

In this example the set backend service policy routes requests based on the version value passed in the query string to a different backend service than the one specified in the API.

Initially the backend service base URL is derived from the API settings. So the request URL https://contoso.azure-api.net/api/partners/15?version=2013-05&subscription-key=abcdef becomes http://contoso.com/api/10.4/partners/15?version=2013-05&subscription-key=abcdef where http://contoso.com/api/10.4/ is the backend service URL specified in the API settings.

When the <choose> policy statement is applied the backend service base URL may change again either to http://contoso.com/api/8.2 or http://contoso.com/api/9.1, depending on the value of the version request query parameter. For example, if the value is "2013-15" the final request URL becomes http://contoso.com/api/8.2/partners/15?version=2013-05&subscription-key=abcdef.

If further transformation of the request is desired, other Transformation policies can be used. For example, to remove the version query parameter now that the request is being routed to a version specific backend, the Set query string parameter policy can be used to remove the now redundant version attribute.

Example

<policies>
    <inbound>
        <set-backend-service backend-id="my-sf-service" sf-partition-key="@(context.Request.Url.Query.GetValueOrDefault("userId","")" sf-replica-type="primary" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

In this example the policy routes the request to a service fabric backend, using the userId query string as the partition key and using the primary replica of the partition.

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, backend

• Policy scopes: all scopes

Set body

Use the set-body policy to set the message body for incoming and outgoing requests. To access the message body you can use the context.Request.Body property or the context.Response.Body, depending on whether the policy is in the inbound or outbound section.

For more information, see the context.Request.Body, context.Response.Body, and the IMessage sections in the Context variable table.

Policy statement

<set-body>new body value as text</set-body>

Examples

Literal text example

<set-body>Hello world!</set-body>

Example accessing the body as a string. Note that we are preserving the original request body so that we can access it later in the pipeline.

<set-body>
@{ 
    string inBody = context.Request.Body.As<string>(preserveContent: true); 
    if (inBody[0] =='c') { 
        inBody[0] = 'm'; 
    } 
    return inBody; 
}
</set-body>

Example accessing the body as a JObject. Note that since we are not reserving the original request body, accessing it later in the pipeline will result in an exception.

<set-body> 
@{ 
    JObject inBody = context.Request.Body.As<JObject>(); 
    if (inBody.attribute == <tag>) { 
        inBody[0] = 'm'; 
    } 
    return inBody.ToString(); 
} 
</set-body>

Filter response based on product

This example shows how to perform content filtering by removing data elements from the response received from the backend service when using the Starter product. For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 34:30. Start at 31:50 to see an overview of The Dark Sky Forecast API used for this demo.

<!-- Copy this snippet into the outbound section to remove a number of data elements from the response received from the backend service based on the name of the api product -->
<choose>
  <when condition="@(context.Response.StatusCode == 200 && context.Product.Name.Equals("Starter"))">
    <set-body>@{
        var response = context.Response.Body.As<JObject>();
        foreach (var key in new [] {"minutely", "hourly", "daily", "flags"}) {
          response.Property (key).Remove ();
        }
        return response.ToString();
      }
    </set-body>
  </when>
</choose>

Using Liquid templates with set body

The set-body policy can be configured to use the Liquid templating language to transform the body of a request or response. This can be very effective if you need to completely reshape the format of your message.

Convert JSON to SOAP using a Liquid template

<set-body template="liquid">
    <soap:Envelope xmlns="http://tempuri.org/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <soap:Body>
            <GetOpenOrders>
                <cust>{{body.getOpenOrders.cust}}</cust>
            </GetOpenOrders>
        </soap:Body>
    </soap:Envelope>
</set-body>

Transform JSON using a Liquid template

{
"order": {
    "id": "{{body.customer.purchase.identifier}}",
    "summary": "{{body.customer.purchase.orderShortDesc}}"
    }
}

Elements

Properties

For accessing information about the request and response, the Liquid template can bind to a context object with the following properties:

context.
    Request.
        Url
        Method
        OriginalMethod
        OriginalUrl
        IpAddress
        MatchedParameters
        HasBody
        ClientCertificates
        Headers

    Response.
        StatusCode
        Method
        Headers
Url.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

OriginalUrl.
    Scheme
    Host
    Port
    Path
    Query
    QueryString
    ToUri
    ToString

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound, backend

• Policy scopes: all scopes

Set HTTP header

The set-header policy assigns a value to an existing response and/or request header or adds a new response and/or request header.

Inserts a list of HTTP headers into an HTTP message. When placed in an inbound pipeline, this policy sets the HTTP headers for the request being passed to the target service. When placed in an outbound pipeline, this policy sets the HTTP headers for the response being sent to the gateway’s client.

Policy statement

<set-header name="header name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple headers with the same name add additional value elements-->
</set-header>

Examples

Example

<set-header name="some header name" exists-action="override">
    <value>20</value>
</set-header>

Forward context information to the backend service

This example shows how to apply policy at the API level to supply context information to the backend service. For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30. At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward some context information, user id and the region the gateway is hosted in, to the backend service for logging or evaluation -->
<set-header name="x-request-context-data" exists-action="override">
  <value>@(context.User.Id)</value>
  <value>@(context.Deployment.Region)</value>
</set-header>

For more information, see Policy expressions and Context variable.

Elements

Properties

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound, backend, on-error

• Policy scopes: all scopes

Set query string parameter

The set-query-parameter policy adds, replaces value of, or deletes request query string parameter. Can be used to pass query parameters expected by the backend service which are optional or never present in the request.

Policy statement

<set-query-parameter name="param name" exists-action="override | skip | append | delete">
    <value>value</value> <!--for multiple parameters with the same name add additional value elements-->
</set-query-parameter>

Examples

Example

<set-query-parameter>
  <parameter name="api-key" exists-action="skip">
    <value>12345678901</value>
  </parameter>
  <!-- for multiple parameters with the same name add additional value elements -->
</set-query-parameter>

Forward context information to the backend service

This example shows how to apply policy at the API level to supply context information to the backend service. For a demonstration of configuring and using this policy, see Cloud Cover Episode 177: More API Management Features with Vlad Vinogradsky and fast-forward to 10:30. At 12:10 there is a demo of calling an operation in the developer portal where you can see the policy at work.

<!-- Copy this snippet into the inbound element to forward a piece of context, product name in this example, to the backend service for logging or evaluation -->
<set-query-parameter name="x-product-name" exists-action="override">
  <value>@(context.Product.Name)</value>
</set-query-parameter>

For more information, see Policy expressions and Context variable.

Elements

Properties

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, backend

• Policy scopes: all scopes

Rewrite URL

The rewrite-uri policy converts a request URL from its public form to the form expected by the web service, as shown in the following example.

• Public URL - http://api.example.com/storenumber/ordernumber

• Request URL - http://api.example.com/v2/US/hardware/storenumber&ordernumber?City&State

  This policy can be used when a human and/or browser-friendly URL should be transformed into the URL format expected by the web service. This policy only needs to be applied when exposing an alternative URL format, such as clean URLs, RESTful URLs, user-friendly URLs or SEO-friendly URLs that are purely structural URLs that do not contain a query string and instead contain only the path of the resource (after the scheme and the authority). This is often done for aesthetic, usability, or search engine optimization (SEO) purposes.

Policy statement

<rewrite-uri template="uri template" copy-unmatched-params="true | false" />

Example

<policies>
    <inbound>
        <base />
        <rewrite-uri template="/v2/US/hardware/{storenumber}&{ordernumber}?City=city&State=state" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put?c=d -->

<!-- Assuming incoming request is /get?a=b&c=d and operation template is set to /get?a={b} -->
<policies>
    <inbound>
        <base />
        <rewrite-uri template="/put" copy-unmatched-params="false" />
    </inbound>
    <outbound>
        <base />
    </outbound>
</policies>
<!-- Resulting URL will be /put -->

Elements

Attributes

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound

• Policy scopes: all scopes

Transform XML using an XSLT

The Transform XML using an XSLT policy applies an XSL transformation to XML in the request or response body.

Policy statement

<xsl-transform>
    <parameter name="User-Agent">@(context.Request.Headers.GetValueOrDefault("User-Agent","non-specified"))</parameter>
    <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    	<xsl:output method="xml" indent="yes" />
    	<xsl:param name="User-Agent" />
    	<xsl:template match="* | @* | node()">
    		<xsl:copy>
    			<xsl:if test="self::* and not(parent::*)">
    				<xsl:attribute name="User-Agent">
    					<xsl:value-of select="$User-Agent" />
    				</xsl:attribute>
    			</xsl:if>
    			<xsl:apply-templates select="* | @* | node()" />
    		</xsl:copy>
    	</xsl:template>
    </xsl:stylesheet>
  </xsl-transform>

Example

<policies>
  <inbound>
      <base />
  </inbound>
  <outbound>
      <base />
      <xsl-transform>
      	<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    		<xsl:output omit-xml-declaration="yes" method="xml" indent="yes" />
    		<!-- Copy all nodes directly-->
    		<xsl:template match="node()| @*|*">
    			<xsl:copy>
    				<xsl:apply-templates select="@* | node()|*" />
    			</xsl:copy>
    		</xsl:template>
      	</xsl:stylesheet>
    </xsl-transform>
  </outbound>
</policies>

Elements

Usage

This policy can be used in the following policy sections and scopes.

• Policy sections: inbound, outbound

• Policy scopes: all scopes

Next steps

For more information, see the following topics:

• Policies in API Management
• Policy Reference for a full list of policy statements and their settings
• Policy samples