In Apigee, an API product is a collection of API resources combined with a service plan and presented to developers as a bundle. The product can also include some metadata specific to your business for monitoring or analytics.
API Products are the central mechanism for authorization and access control to your APIs. In Apigee, API Keys are provisioned, not for APIs themselves, but instead for API products. In other words, API Keys are provisioned for bundles of URIs with an attached service plan.
An API product can be made up of resources from multiple APIs, so you can mix and match resources to create specialized feature sets. Because all resources in an API Product share the same key, it's easy to control access to a specific bundle of resources. For example, you can bundle resources that you only want your internal developers to access, or bundle resources that can only be accessed by paying customers.
TIP: You can set up an API Products with no resources to make it easier to get up and running. You can create a single API Product for all of your developers by using wildcards. (In fact, this is a common use case for initial 'v1' API rollouts.) You can just create a single API Product and provide the base path along with a wildcard. The wildcard will be interpreted by the system at runtime as meaning that any requested resource in the URI tree below the wildcard is permitted.
Developers use your products by adding them to their apps. When they register an app, they have to review the list of products your org provides and then choose which to include. You should take care how you design your products so that developers can easily see all the capabilities your APIs have to offer.
Keys
A product cannot be accessed without an API key. The key is automatically associated with a product when it is added into an app. Because a product can be associated with multiple apps, there might be a large number of keys that provide access to that product. By default, Apigee automatically approves all keys for you.
Manual key approval
You can choose to approve keys manually. If you enable this option, you will have to approve key requests that come in from any app that uses this API product. Requests for key approval appear on the Apps tab. To approve the key click the Approve link that appears in API summary table. See Refresh or revoke API access for more.
You can also create a product that requires manual approval of keys, using the API Product API.
Quotas
You can control the traffic flow for each product by setting up a quota. Quotas can protect your backend servers for high traffic, and differentiate your product line. For example, you might want to bundle resources with a high quota as a premium product and use the same bundle with a lower quota as a basic product.
Scope
As an added level of security, you can associate each product with any scope you defined as part of your OAuth policy. If you have several scopes you need to create a product for each one. For instance, if you have a Read scope and a Read/Write scope, you create two products, one for each scope. When you're creating a product, you need to be aware of all the scopes your organization uses. The scope you attach to a product must match an existing scope or the product is not secure.
Setting up a product
When setting up a product, you select an environment and set key and scope access. You can also set up a quota on the number of calls a product can accept in a set period of time. This can help protect your servers from being overwhelmed if a product is particularly popular.
To add a new API product
- Select Products in the main menu, and click the add (+) button.
- On the Add Products screen, enter a name and description for the product.
- Select the test environment for internal-facing products or the production environment for public-facing products.
- Enable an access level option.
These options determine who can access the product. You can use these levels to control access at different stages of development. For example, you can set a product to Internal Only while it's in development and then change access to Public when it's ready to release. - Enter a service limit number and select a time period (week, hour, minute, second).
This sets up a quota for your product that limits the number of calls the product accepts in a given time period.
- Enter a scope for the product.
The scope should match one of the scopes you defined in your security policy. If they don't match your API may not be secure. - In the API section, click the API menu and select one of the APIs in you org.
- If you want to add the entire API to the product, choose All Resource Paths from the next menu, otherwise choose Selected Resource Paths and click Add API.
- If you chose Selected Resources Paths, you'll see a listing of all the resources in the API. You can delete certain paths to exclude them from the product.
- Click Done.
The new product appears in the All Products table.
Activating an API product
Before you can use your API product you need to configure the APIs you want to use in the product so that they perform the following functions:
- Support the client credentials form of OAuth 2.0 (aka “two-legged OAuth”), so it requires a valid OAuth token on every API call
- Enforces a quota on each application, restricting how many API calls may be made in a day, month, or year
To do this you'll need to attach 2 policies to set up API key validation and quotas:
- API Key Validation- to verify the API key for an API product defined in Apigee. It returns an error if the key is invalid and if it is valid, Apigee looks up the attributes from the API product.
- Rate Limit: Quota - to enforce a quota on the number of API calls your application makes based on the values set in the API product.
In addition, you may need to attach an Assign message policy to set the variable flow.resource.name. This is an important variable because it tells the API Product code which resource is being invoked. This is only required if your API product is not configured with a valid environment, proxies and API resources.
Disabling resources
You can disable resource that you've added to a product. You might want to do this if a resource is malfunctioning or requires more development. When disabled, that API or resource is no longer part of the product. Any app that uses the product can no longer access the disabled resource. Disabled APIs are removed from the product but are not deleted from the system, so they can still be used by other products.
To disable a resource
- In the API Details section of the Add Product window, locate the resource you want to disable, then click the (-) icon. The resource will appear in grey. You can re-enable the resource by clicking the (+) icon.
