API Proxy Configurability

[#1]

There are many situations in which the runtime behavior of API proxies needs to be externally configurable. Generally, these requirements relate to specific operational needs - such as the need to restrict traffic to certain APIs - but they may also apply for business-related needs as well.

There are two main ways in which Apigee enables the behavior of API proxies to be configured externally:

— by storing proxy configuration info in a key-value map or in the Apigee Edge Backend-as-a-Service (BaaS)

— by storing proxy configuration data in custom attributes on the relevant API Product, Developer or Developer Application definition

Storing proxy configuration data in a key-value map or in BaaS is the most effective and flexible approach. Key-value maps - which can be scoped to an entire organization or to specific environments - are optimal for relatively small amount of configuration data. When a key-value map is accessed, the entire value of the map is retrieved by Apigee, not just the value associated with the given key; as a result retrieval of large maps may result in high latency, so the choice of map names and key spaces should take this into consideration. Caching using the PopulateCache/LookupCache/InvalidateCache policies is a good way of mitigating any latency risk and managing cache invalidation when values change.

The Apigee Edge BaaS is capable of handling significantly larger entities than a key-value map and is more effective at storing different types of configuration data for different requests - especially in situations where the configuration data changes frequently in size and content. The BaaS also provides better mechanisms for searching across collections and for tying configuration data to specific users or user devices, as might be needed for personalization or device-specific use cases. BaaS partitions data according to organizations and applications; each application can have its own set of collections, and each collection can contain a different type of data. Entities can be linked either within or across collections, enabling traversal of entity relationships.

Leveraging custom attributes on the API Product is a great way to manage configuration data for all applications authorized to use a given API Product or resource. When an access token is validated, the list of that application’s authorized API Products is checked and information about the API Product that best matches the request is loaded into flow variables in the current request context. Once that information is available the proxy can make run-time decisions based on that information or use the values provided to set information required by certain Apigee policies (such as the Quota policy).

Similarly, custom attributes on the Developer or Developer Application entities can be used to provide developer- or application-specific configurations. The values from these custom attributes are also loaded into the current request context at access token validation time, and can be used in essentially the same way.

In all of the above cases, configuration data can be set externally using Apigee’s Management API or the Apigee Edge BaaS API.

For more information:

Organization- and environment-level key-value maps:

http://apigee.com/docs/api/keyvalue-maps

http://apigee.com/docs/api-services/content/environment-keyvalue-maps

http://apigee.com/docs/api-services/reference/key-value-map-operations-policy

http://apigee.com/docs/api-reference/content/api-proxy-keyvalue-maps

Apigee Edge BaaS:

http://apigee.com/docs/api-baas

Custom attributes:

http://apigee.com/docs/api/api-products-1 (for API Products)

http://apigee.com/docs/api/developers-0 (for Developer entities)

http://apigee.com/docs/api/apps-developer (for Developer Applications)

http://apigee.com/docs/api-services/reference/access-entity-policy

http://apigee.com/docs/api-services/content/oauthv2-policy

[gnanasekaran]

Thanks Chris, can you also provide any usecases/examples either operational or business when using Baas would be more suited than product or app attribues?

[#3]

Given that BaaS is a database, it's capable of doing almost anything 🙂

That said, there are advantage to keeping attributes that relate to a specific resource or group of resources on the API Product, and attributes that relate to a specific application on the Developer Application. The main benefit of this approach is that you don't actually need to *do* anything to access the data - it's made available to you as soon as you validate an API key or an OAuth access token, which most APIs have to do anyway. With BaaS, you'd need to have a BaaS access token and a callout to BaaS (as ServiceCallout or target endpoint) to actually retrieve the data you want.

Simple properties can be easily stored as custom attributes of the API Product, Developer or Developer Application, but I wouldn't use them for any sort of sizeable data. If you have a need to store something like a JSON object with nested properties then BaaS is the way to go. It's also more difficult to store environment-specific data on those entities, so BaaS or KVM would probably be a better fit if you have a need like that.

BaaS is also a better fit for metadata or properties that aren't directly related to resources, developers or applications. End user profile attributes, for example, are a great fit for BaaS (especially if you have a lot of end users); so are entities such as product catalog items, or staged "mobile-enabled" data, or even static images.

Key-value maps (KVMs) are better for much smaller items - service tier data (rate limits and quotas, for example), or other small-ish data that modify proxy behavior.