Managing API products

You're viewing Apigee X documentation.
View Apigee Edge documentation.

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 view 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 if you wish to enforce quota limits on API requests.

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.
    • REST Operations: Groups of API proxies, resource paths, and HTTP methods supported by this API product. You can also define quotas limits for each operation.
    • GraphQL Operations: Groups of API proxies, resource paths, and GraphQL operation types supported by this API product. Supported GraphQL operation types include queries and mutations. You can specify one type or the other, or both. Just like for REST-based API proxies, you can define quota limits on each operation.
    • 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. Specify the API proxy to associate with this API product and, optionally, specify operation details. Operations let you precisely control which REST methods and GraphQL operations have access to which resource paths in an API product, and how many such calls can be made (with Quota).

    REST Operations

    To configure REST operation details, click + in the Operations section. The Add REST 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. 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.

    Adding an API resource

    If you want to use API resources to group your proxies, you can add them using the instructions in this section. However, if you add an API resource you cannot choose to also add operations for the API product.

    To add an API resource:

    1. Click + in the API resources section.

      The Add API resource view displays:

      Add API resource.

    2. Register developer apps with your API product by selecting the checkbox next to their names.
    3. Add resource paths to your API product by selecting the Path option. API product resource paths apply to the path suffix after the base path.

      There are special rules for wildcard support in resource paths, as described in Configuring resource paths.

    4. Click Add. Apigee adds the API resource to your API product.

      After you add an API resource to your API product, you cannot change it. To change a resource you already added, you must remove the resource from the API product and re-add it with the new settings.

    GraphQL Operations

    To configure GraphQL operation details, click + in the Operations section. The Add GraphQL Operation view displays:

    Add a new operation for the API product.

    When you add a new GraphQL operation, you must specify the API proxy to be associated with that operation. The name, operation type, and quota settings are optional.

    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 (or GraphQL operation types), 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.

  4. If you are defining an operation for a REST-based API proxy, click + or Add an operation under REST Operations.

    If you are defining an operation for a GraphQL-based API proxy, click + or Add an operation under GraphQL Operations.

    Apigee displays the configuration dialog for the operation you selected.

  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. The Operation section differs slightly depending on whether you are configuring for REST or GraphQL.

    The following table describes the fields in this section:

    Field Required? Supported operation Description
    Path Required REST only

    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 REST only

    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 Queries and Mutations.

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

    Operation type Optional GraphQL only

    Select one or more GraphQL operation types in the drop-down list. Apigee allows requests to the API proxy that only match the operation types you select.

    The default is no selection, which allows requests with any operation type.

    If you do not select at least one type, 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 Queries and Mutations.

    Quota Optional REST and GraphQL

    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. (Optional) If Apigee Monetization is enabled, create a rate plan for the API product by clicking Add.
  7. 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).