—Rate this article—
 

Using the Edge management API to Publish APIs

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

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

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

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

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 Base Path defined for this API proxy is /weather, that means that only requests to /weather/forecastrss are permitted by this API product.

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, '/' 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 Creating API products for information on changing the behavior of this default.

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

Array of attributes that may be used to extend the default API product profile with customer-specific metadata.

Use this property to specify the access level of the API product as either public, private, or internal. For example: 
 
"attributes": [
     {
       "name": "access",
       "value": "public"
     },
     {
       "name": "foo",
       "value": "foo"
     },
     {
       "name": "bar",
       "value": "bar"
     }
  ]
N/A No
scopes A 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": "access", "value": "public"} ],
  "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" : "access",
    "value" : "public"
  },
  "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.

Registering developers

All apps belong to either developers or companies. Therefore, to create an app, you first need to register a developer or company.

This section describes how to register apps for developers. You can use the Companies API to set up a company group and the Company Developers API to add developers to the company. See Companies and Company Developers for more.

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, use the Create Developer API:

$ 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. The app then must pass these credentials as part of every request to an API product associated with the app.

The following request uses the Create Developer App API to register 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 Key Details for a Developer App API:

$ 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"
}

See Get Key Details for a Developer App for more.

Adding an API product to an app and key

To update an app to add a new API product, you actually add the API product to the app's key using the Add API Product to Key API. See Add API Product to Key for more.

Adding an API product to an app key enables the app that holds the key to access the API resources bundled in the API product. The following method call adds a new API product to an app:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
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"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "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 Approve or Revoke Specific Key of Developer App API:

$ 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"
}

See Approve or Revoke Specific Key of Developer App for more.

Approving API products for consumer keys

The association of an API product with a consumer key also has a status. 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 by using the ​Approve or Revoke API Product for a Key for a Developer App API:

$ 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

This cURL command does not return a response. See Approve or Revoke API Product for a Key for a Developer App for more. 

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 Approve or Revoke Specific Key of Developer App API, using the action revoke against the consumer key of the develop app:

$ 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=revoke" \
-u myname:mypass

This cURL command does not return a response. See Approve or Revoke Specific Key of Developer App for more.

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. See Verify API Key policy for more.
  • OAuthV1, “VerifyAccessToken” operation: Verifies the signature, validates an OAuth 1.0a access token and “consumer key”, and matches the app to the API product. See OAuth v1.0a policy for more.
  • 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. See Authorize requests using OAuth 2.0 for more.

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. Edge resolves the API Key or access token to an app profile.
  4. 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. 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 Customer Support.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)