Apigee tech article: Working with Operations within an API Product

[dchiesa1]

Introduction

Last year the Apigee product team introduced a new feature in Apigee X and hybrid: API Product operations. I don't think we described it or demonstrated it in great detail at that time. It's a pretty powerful feature, so I thought I'd put something together to explain it. And, as a bonus, a working tutorial with re-usable proxy definitions so you can try this yourself, in your own Apigee environment. 

What is an API Product, Anyway?

I like to say that in Apigee, there are three foundational concepts, all P-words: the proxy, the product, and the portal.

• The PROXY is the entity onto which an API Publisher can attach policies and management instructions. For example "enforce a configured rate limit" or "verify an OAuth token". As its name suggests, a proxy is a "stand in" for some other service. With an Apigee proxy, a client application doesn't invoke the upstream service directly; it invokes the proxy, and the proxy invokes the upstream service. So within a proxy you need to configure that upstream or target service, as well as the instructions that you want to execute (or the policies that you want to enforce) on each inbound request.
• The PRODUCT, in contrast, is the unit of publishing or exposure. This is the thing that gets exposed to consumer developers who build against APIs that are managed in Apigee. Rather than directly exposing the proxy, we expose the product. This is handy for several reasons: 1. because the same proxy might get exposed in different ways.  As one example, suppose a proxy includes GET and POST operations, but you'd like to subset that, and expose only GET operations to some developers, while other developers might have acess to all of the operations. An API product allows you to do that. 2. to allow different quality of service. An example here: suppose you want to rate limit differently (1000 per hour vs 10000 per hour), for different tiers of partner developers. Again, the product allows you to do that. Think of the product as a way to wrap proxies up with some additional metadata (rate limits, allowed operation sets, and other data). And that product gets exposed via....
• The PORTAL, or the publishing channel. This is a web interface that acts as a catalog of products. Developers sign in, peruse the product list, examine the documentation for various products, maybe try out the APIs interactively, and then they can request credentials for products. The credentials are usually an Client ID and Secret, which the developer can then use to obtain OAuth tokens. Other forms of credentials are also possible - a good example is a public/private keypair. Or, in the simplest case, the developer just uses the Client ID as an API Key.  But the key point here is, the way developers learn about products is through the API Portal, aka "Developer Portal". 

Obviously there's more to Apigee that just proxies, products, and portals, but those are the big foundational pieces that you need to understand in order to get started. 

API Product Operations

The API Product operations feature allows an API publisher to do the "subsetting" I described above, for a given API proxy. Via the Apigee UI, an API publisher can specify the verb+path pairs for an API Product. You could specify GET /foo and POST /foo as the two operations, and that would be a very limited API product. But there are ways to do multiple verbs, and wildcard paths.   Regardless how you do it, each Product will contain a set of operations that it authorizes. When a developer gets a credential, and then uses that credential to invoke the proxy, the credential verification policy that is attached to the proxy will implicitly resolve that credential to the API Product it maps to, and then check that the API Product allows the current, in-flight request. (Credential verification policies include VerifyAPIKey and OAuthV2/VerifyAccessToken).  Suppose my APIKey is "ABC". I send in a request GET /foo with that key, and the proxy listening there (let's call it fooproxy) invokes VerifyAPIKey. That policy resolves that API Key to Product1. The VerifyAPIKey policy then checks whether Product1 allows GET /foo on the fooproxy. All of this happens automatically, implicitly.  If GET /foo is allowed, the VerifyAPIKey policy succeeds. If it's not on the allowed operations list for the product, the the VerifyAPIKey policy stops execution and returns an error to the caller, something like 401 with a message like "invalid API Key for the requested resource" (although you can override this behavior with FaultRules). 

Different API Keys are authorized for different products. In that way, not all API keys will authorize access to all APIs exposed by your platform. That's what you want - you want to be able to control which developers and which apps can invoke the various subsets of your APIs. That's a big part (obviously just a part) of API Management. The Apigee API Product allows you to do that.

This is really valuable. Most enterprises have myriad APIs available.  And they'd like to manage or control the access to those APIs.  Some people should get full access, other developers more limited access.  Some should be able to see X and Y, while others should be able to retrieve only X. Managing the case where you've got lots of APIs, and potentially lots of consumer developers using the APIs, is an MxN problem. And you don't want to have just "binary" on/off access control, where a developer either has access to all of the operations exposed by an internal API, or none of them.  You want finer grained control. That's what the API Product Operations feature allows you to do. That saves you time and money and more importantly, allows you to securely manage who gets to do what. So important in an enterprise.

Seeing it Work

That gives you the basic explanation.  But I know you want to see it work.  I've also pulled together a working tutorial showing all of this. Find it here. In that README, there are instructions that guide you, step-by-step, to installing a sample API proxy into your Apigee environment, and exercising the API Product operations capability. You can do it all through the Cloud Shell, right in your browser.

I'm working on publishing a walk-through video of this as well. Stay tuned.