Was this helpful?

This topic covers the definition of API products. API products enable developers to register apps that consume APIs using API keys and OAuth access tokens. API products are designed to enable you to 'bundle' API resources (URIs) and then publish those bundles to different groups of developers. For example, you may need to publish one set of API resources to your partner developers, while you publish another bundle to external developers. API products enable you to perform this bundling on-the-fly, without requiring any changes to your APIs themselves. An additional benefit is that developer access can 'upgraded' and 'downgraded' without requiring developers to obtain new consumer keys for their apps.

This topic demonstrates provisioning API products, apps, and developers using the Apigee Edge management API. You can also provision API products, developers, and apps using the Apigee Edge management UI. For instructions on using the Edge management UI, see What is an API product?.

API products form the basis of access control on Apigee Edge. To use an API managed by the Apigee Edge, a developer must acquire a consumer key (also known as an 'API key') or an OAuth access token that is approved to use the API resources bundled into an API product.

Configuring API products

You can configure API products using the Edge management UI or the Edge management API. The API enables you to create and manage API products programatically.

Any time you create an API proxy, Apigee Edge generates an associated 'default' API product specifically for that proxy. You can just use the default API products if you do not require Quotas or finer-grained access control.

To set up a minimal API product using the Apigee Edge management API, POST a payload to the /apiproducts resource in your organization.

The following request creates an API product called weather_free. The API product provides access to all APIs exposed by the API proxy called weatherapi that is deployed in the test environment. The approval type is set to auto--any request for access will be approved.

Remember to change the values for myname, mypass, and org_name to match the settings for your account on http://enterprise.apigee.com.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "approvalType": "auto", 
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-u myname:mypass 

Sample response:

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

You have now set up a very basic API product that can be used to restrict access to the API proxy named weatherapi running in the environment called test.

The API product created above implements the most basic scenario--it authorizes requests to an API proxy in an environment. The authorization it defines is not fine grained. Instead, it is coarse-grained. It defines an API product that enables an authorized app to access any API resources exposed by the API proxy running in the test environment. API products expose additional configuration settings that enable you to customize access control to your APIs for different developer groups. For example you can create two API products that provide access to different API proxies. You can also create two API products that provide access to the same API proxies, but with different associated Quota settings..

API product configuration settings

API products expose the following configuration options:

Name Description Default Required?
apiResources

A comma-separated list of URIs 'bundled' into the API product. This provides fine-grained control over the URIs exposed by an API product.

The URIs by default are mapped from the proxy.pathsuffix variable. The proxy path suffix is defined as the URI fragment following the ProxyEndpoint base path. For example, in the sample API product below, the apiResources element is defined to be /forecastrss.Since the BasePath defined for this API proxy is /weather, that means that only requests to /weather/forecastrss are permitted by this API product.

You can define several API products to "bundle" API resources for different business or technical purposes.

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.

N/A No
approvalType Specifies how API keys are approved to access the APIs defined by the API product. If set to manual, the key that is generated for app is in the 'pending' state. Such keys won't work until they have been explicitly approved. If set to Auto, all keys are generated in the 'approved' and work right away. (Auto is typically used for providing access to free/trial API products that provide limited Quota or capabilities.) N/A Yes
attributes Custom attributes that may be used to extend the default API product profile with customer-specific metadata. N/A No
scopes An comma-separated list of OAuth scopes that are validated at runtime. (Apigee Edge validates that the scopes in any access token presented match the scope set in the API product.) N/A No
proxies Named API proxies to which this API product is bound. By specifying proxies, you can bind the API resources listed in the API product to specific API proxies, preventing developers from accessing those URIs via other API proxies. N/A No. If not defined, apiResources must be explicitly defined, and flow.resource.name variable set in AssignMessage policy.
environments Named environments (for example 'test' or 'prod") to which this API product is bound. By specifying one or more environment, you can bind the API resources listed in the API product to specific environment, preventing developer from accessing those URIs via API proxies in another environment. This setting is used, for example, to prevent URIs protected by API proxies in 'prod' from being accessed by API proxies deployed in 'test'. N/A No. If not defined, apiResources must be explicitly defined, and flow.resource.name variable set in AssignMessage policy.
quota Number of requests permitted per app over the time interval specified. N/A No
quotaInterval Number of time units over which quotas are evaluated N/A No
quotaTimeUnit The time unit (minute, hour, day, or month) over which quotas are counted. N/A No
$ curl -H "Content-Type:application/json" -X POST -d \
 '{
  "apiResources": [ "/forecastrss" ], 
  "approvalType": "auto", 
  "attributes":
    [ {"name": "myAttribute", "value": "myValue"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts

Sample Response

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "myAttribute",
    "value" : "myValue"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

A note on scopes

A scope is a concept drawn from OAuth and maps roughly to the concept of a 'permission'. On Apigee Edge, scopes are completely optional. You can use scopes to achieve finer-grained authorization. Every consumer key issued to an app is associated with a 'master scope'. The master scope is the set of all scopes in all API products for this the app has been approved. For apps approved to consume multiple API products, the master scope is the union of all scopes defined in the API products for which the consumer key has been approved.

Bootstrap API products

You might notice that your organization contains one or more API products, even though you have not explicitly created any. This is because Apigee Edge will create 'bootstrap' API products whenever you create a secure API proxy using the management UI. If you look at a bootstrap API product, you will see that it defines only two settings:

  • The name of the API proxy that was created
  • An API resources path of /**

The goal of bootstrap API products is to make your life easier by enabling you to set up API key validation, without requiring you to manually create an API product. This means that access to any API resources in the API proxy that you create will, by default, require apps to present valid API keys. Once you have things working, you can then tweak the API product settings to meet your requirements.

Registering developers

All apps belong to either developers or companies. Therefore, to create an app, you first need to register a developer. You can register a developer using the Edge management UI or using the Edge management API.

Developers are registered in an organization by creating a profile. Note that the developer email that is included in the profile is used as the unique key for the developer throughout Apigee Edge. Arbitrary attributes can be added to the developer profile as needed. The attributes are not interpreted by Apigee Edge, but can be of use in custom analytics, custom policy enforcement, and so on.

For example, to register a profile for a developer whose email address is ntesla@theremin.com:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ { "name" : "project_type", "value" : "public"} ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u myname:mypass 

Sample Response

{
	  "email" : "ntesla@theremin.com",
	  "firstName" : "Nikola",
	  "lastName" : "Tesla",
	  "userName" : "theremin",
	  "organizationName" : "{org_name}",
	  "status" : "active",
	  "attributes" : [ {
	    "name" : "project_type",
	    "value" : "public"
	  } ],
	  "createdAt" : 1343189787717,
	  "createdBy" : "admin@apigee.com",
	  "lastModifiedAt" : 1343189787717,
	  "lastModifiedBy" : "admin@apigee.com"
	}

Registering developer apps

Every app that is registered on Apigee Edge is associated with a developer and an API product. When an app is registered on behalf of a developer, Apigee Edge generates a "credential" (a consumer key and secret pair) that identifies the app.

This credential is 'bound' (in a loose way) to at least one API product. For example, when you create an app in the Edge management UI, there is an option to associate the app with an API product.

The following request registers an app for the developer you created above: ntesla@theremin.com. When registering an app you define a name for the app, a callbackUrl, and a list of one or more API products:
$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u myname:mypass 

The callbackUrl is used by some OAuth grant types (such as authorization code) to validate redirect requests from the app. If you use OAuth, then this value must be set to the same value as the redirect_uri used to make OAuth requests.

Sample Response

{
  "callbackUrl" : "login.weatherapp.com",
  "createdAt" : 1343190620890,
  "createdBy" : "admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "weather_free",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
    "consumerSecret" : "1eluIIdWG3JGDjE0",
    "status" : "approved"
  } ],
  "lastModifiedAt" : 1343190620890,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weatherapp",
  "status" : "approved"
}

Managing consumer keys for apps

Get the consumer key (the API Key) for the app

The credentials for an app, (API product, consumer key and secret) are returned as part of the app profile. An administrator of an organization can retrieve the consumer key at any time.

The app profile displays the value of the consumer key and secret, the status of the consumer key, as well as any API product associations for the key. As an admin, you can retrieve the consumer key profile at any time using the GET method:

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u myname:mypass

Sample Response

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Approving consumer keys

Setting approval type to manual enables you to control which developers can access the resources protected by API products. When API products have key approval set to manual, consumer keys must be explicitly approved. Keys can be explicitly approved using the following method call:

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
 -u myname:mypass

Sample Response

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Ease developer adoption by creating 'introductory' API products that provide minimal Quota settings and access only to non-sensitive proxies and API resources. For the introductory API product, set approval to auto. For full-featured API products, set approval to manual. You can 'promote' apps from the introductory to the production API products by using the Edge management UI, or by using the API call to approve the same consumer key for the production API product. This prevents developers from having to get new consumer keys when they want to 'upgrade' their apps from introductory to production API products.

Approving API products for consumer keys

The association of an API product with a consumer key also has a status. A consumer key can be 'approved' in general, but not approved for a particular API product. For API access to be successful, the consumer key must be approved, and the consumer key must be approved for the appropriate API product. The association of a consumer key with an API product can be approved as follows:

$ curl -X POST -H "Content-type:application/octet-stream" \ https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u myname:mypass

Revoking API products for consumer keys

There are many reasons why you may need to revoke a consumer key's association with an API product. You may need to remove an API product from a consumer key due to non-payment by the developer, an expired trial period, or When an app is promoted from one API product to another.

To revoke the association of a consumer key with an API product, use the following method, using the action revoke against the consumer key of the develop app:

$ curl -X POST -H "Content-type:application/octet-stream" \ https://api.http://enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u myname:mypass

Enforcing API product settings

API product settings are enforced by matching policies, such as VerifyAPIKey, OAuthV2, and Quota. Until those policies are attached to API proxies, API products and quotas will not be enforced by Apigee Edge.

For API products to be enforced, one of the following policy types must be attached to the API proxy flow:

  • VerifyAPIKey: Takes a reference to an API key, verifies that it represents a valid app, and matches the API product
  • OAuthV1, “VerifyAccessToken” operation: Verifies the signature, validates an OAuth 1.0a access token and “consumer key”, and matches the app to the API product
  • OAuthV2, “VerifyAccessToken” operation: Verifies that the OAuth 2.0 access token is valid, matches the token to the app, verifies that the app is valid, and then matches the app to an API product
  • GetAPIProduct: Enables policies to use API product metadata without necessarily verifying a token

Once policies and API products are configured, the following process is executed by Apigee Edge:

  1. A request is received by Apigee Edge and routed to the appropriate API proxy
  2. A policy is executed that verifies the API key or OAuth access token presented by the client
  3. Apigee Edge resolves the API Key or access token to an app profile
  4. Apigee Edge resolves the list (if any) of API products associated with the app
  5. The first API product that matches is used to populate Quota variables
  6. If no API product matches the API key or access token, then the request is rejected
  7. Apigee Edge enforces URI-based access control (environment, API proxy, and URI path) based on the API product settings, along with Quota settings

Get help

Post questions to the Apigee Developer Forum.

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.