Introduction

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation.
info

The following sections introduce you to API products and related key concepts.

What is an API product?

As an API provider, you create API products to bundle your APIs and make them available to app developers for consumption. You can think of API products as your product line.

Specifically, an API product bundles together the following:

  • Collection of API resources (URIs)
  • Service plan
  • Metadata specific to your business for monitoring or analytics (optional)

The API resources bundled in an API product can come from one or more APIs, so you can mix and match resources to create specialized feature sets, as shown in the following figure.

You can create multiple API products to address use cases that solve specific needs. For example, you can create an API product that bundles a number of mapping resources to enable developers to easily integrate maps into their applications. In addition, you can set different properties on each API product, such as different pricing levels. For example, you might offer the following API product combinations:

  • An API product offering a low access limit, such as 1000 requests per day, for a bargain price. A second API product providing access to the same resources, but with higher access limit and a higher price.
  • A free API product offering read-only access to resources. A second API product providing read/write access to the same resources for a small charge.

In addition, you can control access to the API resources in an API product. For example, you can bundle resources that can be accessed by internal developers only or by paying customers only.

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 for API products. In other words, API keys are provisioned for bundles of resources with an attached service plan.

App developers access your API products by registering their apps, as described in Registering apps. When an app attempts to access an API product, authorization is enforced by Apigee at runtime to ensure that:

  • The requesting app is permitted to access a particular API resource.
  • The requesting app has not exceeded the permitted quota.
  • If defined, the OAuth scopes defined in the API product match those associated with the access token presented by the app.

Understand key concepts

Review the following key concepts before you create your API products.

API 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.

The consumer key or access token act as request credentials. The app developer embeds the consumer key into the app, so that when the app makes a request to an API hosted by Edge, the app passes the consumer key in the request in one of the following ways:

  • When the API uses API key verification, the app must pass the consumer key directly.
  • When the API uses OAuth Token verification, the app must pass a token which has been derived from the consumer key.

API key enforcement doesn't happen automatically. Whether using the consumer key or OAuth tokens as request credentials, the API Proxy validates the request credentials in your API proxies by including a VerifyAPIKey policy or an OAuth/VerifyAccessToken policy, in the appropriate flow. If you do not include a credential enforcement policy in your API Proxy, any caller can invoke your APIs. For more information, see Verify API Key policy.

To verify the credentials passed in the request, Edge performs the following steps:

  • Get the credentials that are passed with the request. In the case of OAuth token verification, Edge verifies that the token is not expired, and then looks up the consumer key that was used to generate the token.
  • Retrieve the list of API products to which the consumer key has been associated.
  • Confirm that the current API Proxy is included in the API Product, and if the current resource path (URL path) is enabled on the API Product.
  • Verify that the consumer key is not expired or revoked, check that the app is not revoked, and check that the app developer is active.

If all of the above checks pass, the credential verification succeeds.

Bottom line, Edge automatically generates consumer keys, but API publishers have to enforce key checking in API proxies by using appropriate policies.

Automatic versus manual approval

By default, all requests to obtain a key to access an API product from an app are automatically approved. Alternatively, you can configure the API product to approve keys manually. In this case, you will have to approve key requests from any app that adds the API product. For more information, see Register apps and manage API keys.

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 popular and receiving a large amount of requests.

For information on configuring quota, see Quota policy. For information on on using product quota settings in quota policies, see the following community article How do the quota settings on an API product interact with quota policies in an API proxy?.

OAuth scopes

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 OAuth2 scopes.

Access levels

When defining an API product, you can set the following access levels.

Access level Description
Public API products that are available to all developers. You can add them to integrated or Drupal-based developer portals.
Private or Internal only

API products that are designed for private or internal use.

Note: There is no functional difference between Private and Internal only access levels. Choose the label that best describes the API product's intended audience.

For the integrated portal, you can add private or internal only API products and make them available to app developers, as required.

For Drupal-based developer portals, you can manage access to Private or Internal only API products on your developer portal, as described in the following sections:

  • For Drupal 9 developer portals, you can configure access to Private or Internal only API products on your developer portal, as described in Configure access permissions to API products.
  • For Drupal 7 developer portals, you cannot add Private or Internal only API products to your developer portal. To make Private or Internal only API products available to app developers, you must add them manually to a registered app from the Edge management UI or API, as described in Register apps and manage API keys. Once added, the developer sees the API product associated with the app in your portal, as described in Managing API products in an app. If the app developer disables access to an API product that is internal or private, the API product is removed from the app and must be re-added manually by the portal administrator.