MonetizationLimitsCheck policy

You're viewing Apigee X documentation.
View Apigee Edge documentation.

policy icon

About the MonetizationLimitsCheck policy

The MonetizationLimitsCheck policy enables you to enforce monetization limits.

Specifically, the policy is triggered if the app developer accessing the monetized API has not purchased a subscription to the associated API product. In this case, The MonetizationLimitsCheck policy will raise a fault and block an API call. For more information, see Enforcing developer subscriptions to API products.

When you attach the MonetizationLimitsCheck policy to an API proxy, the mint.limitscheck.* and mint.subscription_* flow variables are populated, as described in the mint flow variable reference.

Sample

In the following sample, if the app developer accessing the monetized API has not purchased a subscription to the associated API product access to the API is blocked and a 403 status is returned with a custom message.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType="text/xml">
        <error>
          <messages>
            <message>Usage has been exceeded ({mint.limitscheck.isRequestBlocked}) or app developer has been suspended</message>
          </messages>
        </error>
      </Payload>
      <StatusCode>403</StatusCode>
      <ReasonPhrase>Forbidden</ReasonPhrase>
    </Set>
  </FaultResponse>
</MonetizationLimitsCheck>

Element reference

The element reference describes the elements and attributes of the MonetizationLimitsCheck policy.

<MonetizationLimitsCheck continueOnError="[true|false]" enabled="[true|false]" name="policy_name">
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<MonetizationLimitsCheck>

<MonetizationLimitsCheck> element

Defines the MonetizationLimitsCheck policy.

The <MonetizationLimitsCheck> element uses the following syntax (default values are shown):

<MonetizationLimitsCheck continueOnError="false" enabled="true" name="MonetizationLimitsCheck-1">

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

The following table provides a high-level description of the child elements of <MonetizationLimitsCheck>.

Child Element Required Description
<IgnoreUnresolvedVariables> Optional Ignores any unresolved variable error in the Flow.
<FaultResponse> Optional Defines the response message returned to the requesting client.

<IgnoreUnresolvedVariables> element

(Optional) Ignores any unresolved variable error in the Flow. Valid values: true/false. Default true.

<FaultResponse> element

(Optional) Defines the response message returned to the requesting client. FaultResponse uses the same settings as the AssignMessage policy.

<FaultResponse><AssignVariable> element

Assigns a value to a destination flow variable. If the flow variable does not exist, then AssignVariable creates it.

For example, use the following code to set the variable named myFaultVar in the MonetizationLimitsCheck policy:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
</FaultResponse>

A policy in a fault rule can then access the variable. For example, the following Assign Message policy uses the variable to set a Header in the fault response:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> in the MonetizationLimitsCheck policy uses the same syntax as the <AssignVariable> element in the AssignMessage policy.

<FaultResponse><Add>/<Headers> element

Adds HTTP headers to the error message. Note that the empty header <Add><Headers/></Add> does not add any header. This example copies the value of the request.user.agent flow variable into the header.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Default:

N/A

Presence:

Optional

Type:

String

<FaultResponse><Copy> element

Copies information from the message specified by the source attribute to the error message.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

Default:

N/A

Presence:

Optional

Type:

String

Attributes

 <Copy source="response">
Attribute Description Presence Type
source

Specifies the source object of the copy.

  • If source is not specified, it is treated as a simple message. For example, if the policy is in the request flow, then the source defaults to the request object. If the policy is in the response flow, it defaults to the response object. If you omit source, you can use an absolute reference to a flow variable as the source of the copy. For example, specify the value as {request.header.user-agent}.
  • If the source variable cannot be resolved, or resolves to a non-message type, <Copy> fails to respond.
Optional String

<FaultResponse><Copy>/<Headers> element

Copies the specified HTTP header from the source to the error message. To copy all headers, specify <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

If there are multiple headers with the same name, use the following syntax:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

This example copies "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not copied.

Default:

N/A

Presence:

Optional

Type:

String

<FaultResponse><Copy>/<StatusCode> element

The HTTP status code to copy from the object specified by the source attribute to the error message.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Default:

false

Presence:

Optional

Type:

String

<FaultResponse><Copy>/<ReasonPhrase> element

The reason description to copy from the object specified by the source attribute to the error message.

<Copy source='response'>
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Copy>

Default:

false

Presence:

Optional

Type:

String

<FaultResponse><Remove>/<Headers> element

Removes specified HTTP headers from the error message. To remove all the headers, specify <Remove><Headers/></Remove>. This example removes the user-agent header from the message.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

If there are multiple headers with the same name, use the following syntax:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

This example removes "h1", "h2", and the second value of "h3". If "h3" has only one value, then it is not removed.

Default:

N/A

Presence:

Optional

Type:

String

<FaultResponse><Set> element

Sets information in the error message.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

Default:

N/A

Presence:

Optional

Type:

N/A

<FaultResponse>/<Set>/<Headers> element

Sets or overwrites HTTP headers in the error message. Note that the empty header <Set><Headers/></Set> does not set any header. This example sets the user-agent header to the message variable specified with the <AssignTo> element.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Default:

N/A

Presence:

Optional

Type:

String

<FaultResponse>/<Set>/<Payload> element

Sets the payload of the error message.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Set a JSON payload:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

In a JSON payload, you can insert variables using the variablePrefix and variableSuffix attributes with delimiter characters as shown in the following example.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

or, as of cloud release 16.08.17, you can also curly braces to insert variables:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Set a mixed payload in XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Default:

Presence:

Optional

Type:

String

Attributes

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">
Attribute Description Presence Type
contentType

If contentType is specified, its value is assigned to the Content-Type header.

Optional String
variablePrefix Optionally specifies the leading delimiter on a flow variable because JSON payloads cannot use the default "{" character. Optional Char
variableSuffix Optionally specifies the trailing delimiter on a flow variable because JSON payloads cannot use the default "}" character. Optional Char

<FaultResponse>/<Set>/<StatusCode> element

Sets the status code of the response.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

<FaultResponse>/<Set>/<ReasonPhrase> element

Sets the reason phrase of the response.

<Set source='request'>
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Default:

false

Presence:

Optional

Type:

Boolean

Flow variables

The following predefined flow variables that are automatically populated when the MonetizationLimitsCheck policy executes. For more information, see mint flow variables.

Flow variable Description
mint.limitscheck.is_request_blocked false if an API subscription is found
mint.limitscheck.is_subscription_found true if an API subscription is found.
mint.limitscheck.purchased_product_name Name of the purchased API product. For example: MyProduct
mint.limitscheck.status_message Status message. For example: limits_check_success
mint.subscription_end_time_ms End time of the API product subscription.
mint.subscription_start_time_ms Start time of the API product subscription. For example: 1618433956209

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to false to return an error when a policy fails. This is expected behavior for most policies. Set to true to have flow execution continue even after a policy fails.
enabled true Optional Set to true to enforce the policy. Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.