Developing on a new platform takes time to become fluent in its behavior and optimal configurations. To accelerate this for anyone working with Apigee Edge, we've gathered a handful of must-know items to aid your success on the platform.
Below you'll find tips, learnings, and gotchas grouped by functionality or concept. Keep in mind that this article will evolve with the Apigee products, so check back often!
Caching
- If you're trying to provide HTTP response caching for your APIs, use the ResponseCache policy (vs. PopulateCache/LookupCahe). ResponseCache provides built-in proxy logic to skip unnecessary policies when there is a cachehit.
- When using the ResponseCache policy for lookup in a request flow, all policies defined in that same flow after ResponseCache will still execute. Policies in subsequent request flows will automatically be skipped when there's a cachehit and processing will continue after the ResponseCache policy definition in the response.
- When using any caching policy, you should create and reference a defined cache resource. This will allow you to group your cached entries and provide better granularity around clearing the cache.
- For more detail about how caching works, see the following article: Apigee Edge Caching In Detail
Key-Value Maps (KVMs)
KVMs provide long-term data persistence. You should consider the following information about their lower level functionality when designing your APIs in Edge:
- When using the KVM policy, the whole key-value map is retrieved, even if you are accessing a single entry by its key (don't worry, we're working to make this better in the product). Because of this, larger key-value maps can have negative performance impacts. Do not increase its size over time without purging old, stale data. We recommend limiting the use of KVMs to configuration data and look at Apigee's API BaaS feature for larger data sets.
- Edge handles single KVM entries as multi-valued if it contains commas. It will split the value, by comma, into an array so it can be accessed using an index. Even when you don't specify an index in the KVM policy, it will still split the value and then join it back, causing unnecessary processing. This is important when it ends up separating thousands of values, for thousands of API requests per second. Instead, use anything other than a comma for separation -- we tend to use a pipe | .
- You can reduce requests to the datastore by leveraging the built-in cache functionality of KVM lookups with a simple configuration in the policy: <ExpiryTimeInSecs>300</ExpiryTimeInSecs>. This setting only pertains to the lookup's cache expiry as KVM data does not expire in the datastore.
Flow Processing
- Conditional flows are evaluated in both the Proxy and Target endpoints. If you are mediating an API request in the Proxy endpoint, be cautious that you might need to use a different condition for the flow in the Target endpoint. Especially for REST to SOAP translations, you may overwrite the request.verb variablefrom GET to POST. In this case, request.verb can return different values in Proxy endpoint processing vs. Target endpoint processing.
Fault Handling
- FaultRules behave almost the same as conditional flows. You can have 0 or more conditional FaultRule flows inside an endpoint. There's one gotcha, though. Each FaultRule condition is evaluated bottom-up! -- reverse of the normal top-down conditional flow evaluation in a Proxy or Target endpoint.
Service Callouts
- The HTTP request message for a service callout can be directly set within the ServiceCallout policy. It is not required to use an AssignMessage policy beforehand as some functionality of AssignMessage already exists in ServiceCallout. To set the callout's request message, use the same <Set> configuration from AssignMessage inside an element named <Request> directly in the ServiceCallout policy.
What learnings do you have to share? @Michael Russo
LinkedIn
Twitter
