What's a policy?

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Apigee Edge 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 Edge. You can also write custom scripts and code (such as JavaScript and Node.js applications), that extend API proxy functionality and enable you to innovate on top of the basic management capabilities supported by Apigee Policies.

Watch this video for an introduction to policy attachment and enforcement.

Policy types

Technically, a policy is an XML-formatted configuration file. Each policy type'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.

Edge Policy types are grouped into the following functional categories:

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 API Services, 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 API Services to implement custom behavior in the programming language of you choice.

Each Policy type is documented in detail in the Policy reference overview. This topic demonstrates general interaction, showing you how to create Policies, and how to attach them to Flows in an API proxy configuration.

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 management UI or the management 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 this Quota configuration, 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 1 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 API Services.

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