Managing API products

API products bundle your APIs and make them available to app developers for consumption. For an overview of API products, see What is an API product?

Exploring the API Products view

The API Products displays all your API products and some details about each one. You use this part of the Apigee UI to create, edit, and delete API products.

To access the API Products view:

  1. Sign in to the Apigee UI.
  2. Select Publish > API Products.

    Apigee displays the API Products view, as the following example shows:

    The API Products view displays the list of API products. Callouts show the
        tasks you can accomplish, listed below the figure.

    From the API Products view, you can perform the following common tasks:

    These tasks are described in the sections that follow.

Adding an API product

This section describes how to add an API product by using the Apigee UI.

When you add a new API product, be sure that you include the appropriate security policies (such as VerifyAPIKey policy or OAuthv2 policy) in your API proxies and attach a Quota policy in the flow.

To add an API product by using the Apigee UI:

  1. Sign in to the Apigee UI.
  2. Select Publish > API Products. Apigee displays the API Products view.
  3. Click +API Product.

    Apigee displays the New Product view, as the following example shows:

    Add a new API product.

    This example shows the primary parts of a new API product:

    • Product details: Basic information about the API product such as its name, access level (private, public, or internal), and OAuth scopes.
    • Operations: Groups of API proxies, resource paths, and HTTP methods supported by this API product. You can define quotas and custom attributes on each operation or operation group. (Not shown: API resources. If you have not yet opted in to using the new configuration, you will only be able to use API resources as an organizational model for your proxies within the API product. API resources are apps, API proxies, and remote services that your API product is mapped to.)
    • Custom attributes: Key/value pairs that help you control API proxy execution.

    Each of these sections is described in the following steps.

  4. In the Product details section, enter basic information about your new API product. The following table describes the fields in this section:

    Field Required? Description
    Name Required

    Defines the internal name of the API product. You use this value in calls to the Apigee API that reference the API product. The value of the Name field can include alphanumeric characters, spaces, and the following: _ - . # $ %

    For example, My API Product, my-product.

    Display name Required

    Defines the name used in the Apigee UI for the API product. You can edit the display name of the API product at any time.

    The Display name can include special characters.

    For example, <My> API Product!!!.

    Description Optional

    A string that can help you remember the purpose or function of the API product. The description can include special characters.

    For example, The one where I let dev apps read but not write to the "/porkbellyfutures" endpoints.

    Environment Optional

    Identifies which environments the API product allows access to.

    The environments that you select in this field restrict access to API proxies based on where they are deployed. For example, if API proxy A is deployed to both the test and prod environments, but the API product only has the test environment selected, then an API call for the corresponding developer app only allows access to API proxy A deployed in the test environment.

    Access Required The access level given to users of this API product. For details, see Access levels.
    Automatically approve access requests Optional (defaults to selected)

    Enables automatic approval of key requests that come in for this API product from any app. To require manual key approval, disable this option.

    The default is selected, which means this API product automatically approves key requests.

    If you select manual key approval, you must approve key requests that come in from any app that uses this API product. To manually approve keys:

    • UI: Select Publish > Apps, select the app and edit it. Then click Approve.
    • API: Use the Developer app keys API.

    For more information, see Registering apps and managing API keys.

    Quota Optional

    Defines limits on the number of requests allowed for this API product. This value applies to the sum of all operations' requests for this API product.

    This value is superseded by more specific quota limits set on operations that you define on the API product.

    Entering a quota value does not automatically enforce restrictions on the number of calls that can be made through the API product. You must also add the Quota policy to API proxies that are referenced by the API product.

    For more information, see Quotas.

    Allowed OAuth scope Optional If you are using OAuth with the API product, enter a comma-separated list of OAuth scopes that you want the API product to allow (such as Read or other scopes that apps send with their API calls). For more information, see OAuth scopes.
  5. (Optional) Add operations to your API product. Operations let you precisely control which REST methods have access to which resources in an API product, and how many such calls can be made (via Quota).

    To add a new operation, click + in the Operations section. The Add Operation view displays:

    Add a new operation for the API product.

    When you add a new operation, you must specify, at a minimum, the source for that operation as well as a resource path. Specific methods and quotas are not required.

    For more information, see Adding operations to an API product.

    If you don't see the Operations section in New Product view, but instead see API Resources, then you have not yet opted into using the new functionality, as described at the beginning of this section.

    Google recommends that you use operations rather than API resources when defining API products. You can, however, continue to use API resources, as described in the next section.

  6. (Optional) Add custom attributes to your API product.

    Custom attributes are key/value pairs that can be used in many ways, including helping control API proxy execution.

    In total, an API product can have up to 18 custom attributes, including those set on operations.

    For example, you can create a custom attribute called deprecated with a value of true or false. In your API proxy flow, you can check the value of the API product's deprecated attribute. If its value is true, you can throw an error with the RaiseFault policy because you want that operation to behave as if it is deprecated and no longer supported.

  7. Click Save. Apigee creates the new API product.
  8. After adding a new API product be sure that you also:

    1. Include the appropriate security policy in your API proxies, such as VerifyAPIKey policy or OAuthv2 policy. API products use API keys and/or OAuth access tokens to enforce API access.

      For more information, see API keys and OAuth.

    2. Attach a Quota policy in the flow. Otherwise, your API product quota settings will not be applied.

Adding operations to an API product

Operations define sources, supported HTTP methods, and quotas for requests that match that operation.

The maximum number of operations you can add to an API product is 50.

To add an operation to an API product:

  1. Sign in to the Apigee UI.
  2. Select Publish > API Products.
  3. In the list of API products, select the one to which you want to add an operation.

    Apigee displays details about that API product, as the following example shows:

    Details about an API product

  4. In the Operations section, click + or Add an operation, as the following example shows:

    Operations section of API product view.

    Apigee displays the Add Operation view:

    Details about an API product

  5. In the Source section, specify a resource for the operation. Unless you use Apigee Adapter for Envoy, you'll use an API proxy as your source.

    • (Default) API Proxy: Select an API proxy from the drop-down list to be the source for your API product.
    • (Apigee Adapter for Envoy only) Binds the API product to one or more remote service targets. If you select Remote Service, then enter the service's domain; for example, httpbin.org. The Remote Service field will not be visible to you unless you have installed Apigee Adapter for Envoy.
  6. In the Operation section, add one or more resource paths and specify any HTTP method restrictions or quotas for those paths.

    The following table describes the fields in this section:

    Field Required? Description
    Path Required

    Enter the resource path for the operation.

    You can use the operation path to allow or disallow requests to specific URIs. For example, if you set the operation's source to the music API proxy with a base path of /music, the API product allows calls to all the subpaths under /music. However, if you want the API product to allow access to only the venues resource path which has a URI of /music/venues, add the /venues as the operation's path. You can do this for all operations, or for specific operations.

    In this case, calls to /music/venues?name=paramount are allowed, but calls to /music/artists?name=Jack%Johnson are blocked.

    Note that there are special rules for wildcards in resource paths, as described in Configuring resource paths.

    Methods Optional

    Select one or more HTTP request methods in the drop-down list. (These methods are sometimes known as HTTP verbs.) Apigee allows requests to the API proxy that only match the methods you select.

    The default is no selection, which allows requests with any HTTP methods.

    If you do not select at least one method, Apigee inserts ALL as the value of this field when you save the operation.

    For information about the functionality of the HTTP request methods, see HTTP request methods.

    Quota Optional

    Defines the quota settings for the API proxy. There are three fields under Quota that you must specify, if you define a quota:

    1. The first field specifies the maximum number of requests to allow from a developer app to the API proxy for the specified period.

      This field corresponds to the <Allow> element in a Quota policy.

    2. The second field specifies the reset frequency (or interval) of the quota.

      This field corresponds to the <Interval> element in a Quota policy.

    3. The third field specifies the reset period type (or time unit), such as day, week, or month.

      This field corresponds to the <TimeUnit> element in a Quota policy.

    The following example sets a limit of 1,000 GET, HEAD, and TRACE requests to the API proxy per day (all other HTTP requests are ignored):

    Add a new quota to an operation

    The following example sets a limit of 42 requests every 3 minutes, regardless of HTTP method, to the /mypath resource:

    Add a new quota to an operation

    When you define a quota for an operation, you are required to enter values for all three fields in the Quota section.

    You cannot define different quotas for multiple HTTP methods on the same operation. To do this, you'll need to create multiple API products and define the method-specific quotas on each one.

    If you set these values in both the Quota policy and on the API product (in the UI as described here or with the API products API, the API product UI/API settings take precedence.

  7. In the Custom Attributes section, define up to three custom attributes on this operation. Custom attributes are name/value pairs that you can access at runtime. Custom attributes set on an operation are populated as flow variables and can be accessed with the following pattern:

    API_PRODUCT_NAME.OPERATION_NAME.attributes.ATTRIBUTE_NAME

    The size of the name plus value of each attribute cannot be more than 2KB.

  8. Click Add to create the new operation and add it to your API product.

Configuring resource paths

Note the following rules for resource paths:

  • /: Indicates that the base path and all subpaths of the base path are supported.
  • /**: Indicates that all subpaths of the base path are supported (but not the base path).
  • /*: Indicates that only URIs one level down from the base path are supported.
  • Resource paths specified on the API product or on its operations apply to all API proxies added to the API product.
  • More inclusive, less specific resource paths take predence over those that are more specific. For example, if you add / and /**, the / resource path takes precedence and the /** resource path is ignored.

The following table shows the default behavior of an API product for different resource paths. In this example, the API proxy has a base path of /v1/weatherapikey. The API product resource path applies to the path suffix after the base path.

Request URI Allowed for / Allowed for /* Allowed for /** Allowed for /*/2/** Allowed for /*/2/*
/v1/weatherapikey
/v1/weatherapikey/
/v1/weatherapikey/1
/v1/weatherapikey/1/
/v1/weatherapikey/1/2
/v1/weatherapikey/1/2/
/v1/weatherapikey/1/2/3/
/v1/weatherapikey/1/a/2/3/

By default, a resource path of / in an API product supports the base path and all subpaths. 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 subpaths, such as /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA, and so on.

With API products, you can change this default so that a resource path of / corresponds only to the base path of the API proxy. This means that the API product will not allow access to a URI that has anything after the /. If you make this change, then in the table above only the first two rows under "Allowed for /" would be allowed.

For additional information, see Making sense of API Product configuration

Editing an API product

To edit an API product:

  1. Sign in to the Apigee UI.
  2. Select Publish > API Products.
  3. Click in the row of the API product that you want to edit. Apigee displays details about the API product.
  4. Click .
  5. Edit the API product's settings, as required.

    You cannot edit an existing API resource. Instead, you must delete the API resource and add a new version with the corrected values if you want to change it.

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

  6. Click Save.

    Your changes take effect within a short period of time (approximately five minutes).

Apigee keeps the following entities in cache for a minimum of 180 seconds after the entities are accessed.

  • OAuth access tokens. This means the ExpiresIn element on the OAuth v2 policy won't be able to expire an access token in less than 180 seconds.
  • Key Management Service (KMS) entities (Apps, Developers, API Products).
  • Custom attributes on OAuth tokens and KMS entities.

Deleting an API product

To delete an API product:

  1. Sign in to the Apigee UI.
  2. Select Publish > API Products.
  3. Position the cursor over the API product in the list.
  4. Click .
  5. After you confirm the delete operation, the deletion takes effect within a short period of time (approximately five minutes).