Provision API products, developers and apps

Was this helpful?

This topic covers the definition of API products, which enable developers to create apps that consume APIs using API keys and OAuth access tokens.

Back to top

Overview

An API product is a list of API resources (URIs) and rate-limiting (quota) settings.

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

Back to top

Configuring API products

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

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

(Remember to change the values for myname, mypass, and org_name to match the settings for your account on 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" ]}' \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts

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.

When you add a security policy to the API proxy called weatherapi running in test, the security policy will check the API key or access token presented by the app. If the API key or access token is not approved, then the request is rejected.

The API product created above implements the most basic scenario--authorizing request to an API proxy in an environments. However, API products expose a additional configuration settings that enable you to enforce dynamic access control over APIs, including defining dynamic Quota settings.

Back to top

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.

 N/A No
approvalType Specifies how consumer keys are approved to access the resources defined by the API product. If set to manual, the consumer 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. (The API Platform 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"}'
}
Back to top

Creating developer profiles

All apps belong to either developer or companies. Therefore, to create an app, you first need to create a developer. You can create a developer using the Management UI or using the 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 the API Platform. Arbitrary attributes can be added to the developer profile as needed. The attributes are not interpreted by the API Platform, but can be of use in custom analytics, custom policy enforcement, and so on.

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

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

Sample Response

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

Registering developer apps

Every app that is created on the API Platform is associated with a developer and an API product. When an app is registered on behalf of a developer, the API Platform 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 API Platform Management UI, there is an option to associate the app with an API product.

$ curl -H "Content-type:application/json" -X POST -d \
      '{"apiProducts": [ "weather_free"], 
        "callbackUrl" : "login.weatherapp.com", 
        "name" : "weatherapp"}' \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theramin.com/apps

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"
}
Back to top

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.

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

Sample Response

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

Approving consumer keys

Consumer keys must be explicitly approved when API products have key approval set to manual. Keys can be explicitly approved using this method call:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theramin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?action=approve

Sample Response

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

Approving API products for consumer keys

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

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theramin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve"

API products settings are enforced by matching policies. Until those policies are set up, API products and quotas are not enforced by the API Platform.

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 verifying a token

Once policies and API products are configured the following process is executed by the API platform:

  1. A request is received by the API platform 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. The API Platform resolves the API Key or access token to an app profile
  4. The API Platform 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. The API Platform enforces URI-based access control (environment, API proxy, and URI path) along with Quota settings

To learn how to configure security and Quota policies to enforce the settings provisioned in this topic, see Secure APIs with API keys

Post questions to the Apigee Developer Forum.

Back to API Platform Developer Guide.

Back to top