Send Docs Feedback

Creating API products

For a full overview of API products, see What is an API product?.

Before you begin

In order for an API product to work correctly, do the following:

  • Include the appropriate security policy in your API proxies, such as Verify API Key or OAuth v2.0. The API product uses API keys and/or OAuth access tokens to enforce API access. For more, see API keys and OAuth home.
  • Add at least one API proxy to the product. If the product contains no API proxies, any app associated with the product can make calls to any API in your entire organization.

This section explains a few key concepts related to API products. It's helpful to familiarize yourself with these concepts before you create a new API product.

Keys

When you register a developer's app in your organization, the app must be associated with at least one API product. As a result of pairing an app with one or more API products, Edge assigns the app a unique consumer key. When the app makes a request to an API resource in an API product, the request must include its unique API key.

API key enforcement doesn't happen automatically. You must enforce API key checking in your API proxies with a policy, such as the Verify API Key policy. Without some type of key enforcement policy, anyone can make calls to your APIs. For more information, see Verify API Key policy.

Bottom line, Edge automatically generates keys, but you have to enforce key checking in your APIs.

Manual key approval

By default, all key requests to an API product from an app are automatically approved. You can instead choose to approve keys manually. If you set this option in the Edge management UI when creating the product, you will have to approve key requests that come in from any app that adds the API product. See Registering apps for more.

Quotas

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. A quota can help protect your servers from being overwhelmed if a product is particularly popular.

Setting quota limits on a product does not automatically enforce quota. It's simply a default limit that can be referenced in quota policies. Here are some advantages of setting a quota on the product for quota policies to reference:

  • Quota policies can use a uniform setting across all API proxies in the API product.
  • You can make runtime changes to the quota setting on an API product, and quota policies that reference the value automatically have updated quota values.

For information on configuring quota, see Quota policy. For information on on using product quota settings in quota policies, see https://community.apigee.com/questions/1488/how-do-the-quota-settings-on-an-api-product-intera.html.

Scope

As an added level of security, you can define any OAuth scopes, as a comma-separated list, that must be present in access tokens sent through the product. When you're creating a product, you need to be aware of all the scopes your organization uses. The scopes you add to a product must match existing scopes or the product is not secure.

For more information about using scopes with Edge OAuth policies, see Working with scopes.

Creating an API product

You can create an API product in the Apigee Edge management UI at https://enterprise.apigee.com or with the management API. This procedure shows the management UI version. For the API version, (see Using the Edge management API to Publish APIs).

To create a new API product:

  1. Login to the Edge management UI at https://enterprise.apigee.com. (You can obtain a free account at https://accounts.apigee.com/accounts/sign_up.)
  2. Click the Publish tab, then Products
  3. Click the (+) Product button.
  4. On the Add Products page, enter a Name. This will be the internal name of the product. You cannot edit the name once the product is created. You cannot use special characters in the name. 
  5. Optionally, enter a Display Name and Description for the API product. The display name shows up in the UI. If you do not enter a display name, the value of the Name field will be used. You can change the display name at any time by editing the product. You can use special characters in the display  name. 
  6. Add at least one API proxy to the product. Click +API Proxy.
    This limits access to the API proxies listed. You'll configure resources later in this procedure.
    If you don't select an API proxy, any app associated with the product can make calls to any API in your entire organization.
  7. Environment: Select the environments the product will allow access to. For example, select the test environment for internal-facing products or the prod environment for public-facing products.
    If you select no environments, the product allows access to all environments.
  8. Specify an Access level.
    • Public - When developers create or modify their developer apps in a Developer Services Portal, they can see and select public products.
    • Internal only or Private - There is no functional difference between these two options. When an API product is internal only or private, the product doesn't appear in the Developer Services Portal. To let a developer use the product, you must manually add the product to a developer app in the management UI or with the management API. Once you do this, the developer sees the product associated with her app in the Developer Services Portal.
  9. Select a Key Approval Type as Automatic or Manual.
    If you select automatic key approval, all key requests that come in from any app that uses this API product are automatically approved. If you select manual key approval, you will have to approve key requests that come in from any app that uses this API product.
  10. Entering a quota Quota limit does not automatically enforce restrictions on the number of calls that can be made through the product. For more information, see the Quota section above.

    Enter a quota limit that you want to reference from quota policies.

  11. Optionally, if you are using OAuth with the API product, enter the Allowed OAuth Scopes that you want the product to allow (such as 'Read' or any other scopes that apps will send with their API calls). You can specify multiple scopes as a comma-separated list. 

    For more about scopes, see Working with scopes.
  12. In the Resources section:

    Adding resources lets you further restrict API access with relation to the API proxies included in the product. For example, let's say you add a "music" API proxy to the product. That means the product allows all calls to the music API. However, you want the product to allow access to only the music/venues resource. By adding a venues** resource, the product allows calls to only that URI pattern. For example, calls to /music/venues?name=paramount go through, but calls to /music/artists?name=Jack%Johnson get rejected.

    You can add resources either by selecting one from an existing API proxy API Proxy, Revision, and a Resource Path (then click Import Resource), or by clicking +Custom Resource and adding a free-form resource pattern.
    You can select a specific path, or you can select all subpaths with a wildcard. Wildcards (/** and /*) are supported. The double asterisk wildcard indicates that all sub-URIs are included. A single asterisk indicates that only URIs one level down are included.

    By default, a Resource Path of '/' supports the same resources as '/**' as well as the Base Path defined by the API proxy. For example, if the Base Path of the API proxy is /v1/weatherapikey, then the API product supports requests to /v1/weatherapikey and to any sub-URIs, such as /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, etc.

    See Configuring the behavior of a Resource Path of '/' on changing the behavior of this default.
  13. Save your product.

Configuring the behavior of a Resource Path of '/'

By default, a Resource Path of '/' in an API product supports the same resources as '/**' as well as the Base Path defined by the API proxy. You can change this default so that a Resource Path of '/' corresponds only to the Base Path of the API proxy, meaning the API product will not allow access to sub-URIs.

To change the default, a system administrator must set the value of the features.isSingleForwardSlashBlockingEnabled property on your organization to true. Cloud customers can make that request to Apigee Support.

Apigee Edge for Private Cloud customers can make a request in the form below to set the property on an organization:

curl -u username:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization name='myorg' type='trial'> \
<Properties> \
<Property name='features.isSingleForwardSlashBlockingEnabled'>true</Property> \
</Properties> \
</Organization>"

Deleting resources 

You can delete resources that you've added to an API product. You might want to do this if a resource is malfunctioning or requires more development. When deleted, that resource is no longer part of the API product. Any app that uses the API product can no longer access the deleted resource. Deleted resources are removed from the product but are not deleted from the system, so they can still be used by other products.

To delete a resource

  • In the API Resource Paths for Product section of the product details window, locate the resource you want to disable, then click Delete in the Actions column.

     

Help or comments?