What's a policy?

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Apigee enables you to program API behavior without writing any code, by using policies. A policy is like a module that implements a specific, limited management function. Policies are designed to let you add common types of management capabilities to an API easily and reliably. Policies provide features like security, rate-limiting, transformation, and mediation capabilities, saving you from having to code and maintain this functionality on your own.

You're not limited to the set of policy types provided by Apigee. You can also write custom scripts and code (such as JavaScript applications), that extend API proxy functionality and enable you to innovate on top of the basic management capabilities supported by Apigee policies.

This topic provides an overview of policy types and use in Apigee. For information on specific policies, see the Policies reference overview.

Policy types and categories

Technically, a policy is an XML-formatted configuration file. Each policy's structure (for example, the required and optional configuration elements) is defined by an XML schema. If you are proficient with XML tools, it is worthwhile to familiarize yourself with the policy schemas in the API Platform samples on GitHub.

Apigee policies are grouped into the following functional categories. The policies available for each policy category are listed in the Policy reference overview.

Traffic management

Policies in the traffic management category enable you to control the flow of request and response messages through an API proxy. These policies support both operational- and business-level control. They give you control over raw throughput, and can also control traffic on a per-app basis. Traffic management policy types enable you to enforce quotas, and they also help you to mitigate denial of service attacks.

Security

Policies in the security category support authentication, authorization, as well as content-based security.

Mediation

Policies in the mediation category enable you to actively manipulate messages as they flow through API proxies. They enable you to transform message formats, from XML to JSON (and vice-versa), or to transform one XML format to another XML format. They also enable you to parse messages, to generate new messages and to change values on outbound messages. Mediation policies also interact with basic services exposed by Apigee, enabling you to retrieve data about apps, developers, security tokens, and API products at runtime.

Extension

Policies in the extension category enable you to tap into the extensibility of Apigee to implement custom behavior in the programming language of you choice.

Attaching policies

In order for a policy to apply to your API proxy, you must attach it to the proxy in a flow. For information, see the other topics in this section, including Attaching and configuring policies in the UI and Attaching and configuring policies in XML files.

Deploying policy changes

For policy changes to take effect, you must deploy the API proxy revision to an environment. After you attach a policy or make changes to an existing policy, use the Apigee UI or the Apigee API to deploy the changes.

Verifying policy enforcement

To verify that a policy is enforced properly, the API must be invoked by an HTTP client. To verify a Quota configuration, set a quota (for example, at one request per minute), then submit multiple requests to the API exceeding the quota limit that you set in the quota policy. (The URI path, configured as the base path setting in the ProxyEndpoint, in the request below is /weather).

http://ORG_NAME-test.apigee.net/weather/forecastrss?w=12797282

After you submit more than one request within a minute, you should see the following error message:

{
   "fault":{
      "faultstring":"policies.ratelimit.QuotaViolation",
      "detail":{
         "errorcode":"policies.ratelimit.QuotaViolation"
      }
   }
}

This indicates that the Quota policy is being enforced by Apigee.

Policy-based fault handling

Note the format of the error message above. It contains a faultstring property and an errorcode property. In many cases, you need to implement some behavior to handle these errors. For example, you may wish to issue a customized message to a developer whose app has exceeded the Quota.

For more on fault handling, see Handling faults.

Best practices: Common policy sets

To meet basic management requirements, API proxies usually enforce the following policies:

Basic API key validation

ProxyEndpoint Request Flow:
  1. SpikeArrest
  2. XMLThreatProtection or JSONThreatProtection
  3. API key validation
  4. Quota
  5. ResponseCache
ProxyEndpoint Response Flow:
  1. ResponseCache

Basic transformation: JSON to XML

Request Flow:
  1. SpikeArrest
  2. JSONThreatProtection
  3. API key validation
  4. Quota
  5. JSONToXML
Response Flow:
  1. XMLToJSON
  2. ResponseCache