Create an API product

Use the POST method to create a new API product in an organization.

An API product is a list of API resources (URIs) with associated quota settings and metadata. The goal of API resources is to enable the definition of API 'bundles' that are selected by app developers at design time. API product settings are enforced on the API Platform at runtime by policies: Authorization (API Key, OAuth 1.0a, OAuth 2.0) and Quota. Client apps present credentials (API keys, OAuth tokens) approved for API products. The association of app keys with API products is a primary method of access control on the Apigee API Platform.

Defining API resources:

An API resource is a URI that equates to the predefined variable proxy.pathsuffix. In other words, an API resource is a URI that occurs in the request path following the base path defined in the ProxyEndpoint configuration.

For example, if a ProxyEndpoint in the environment 'test' in the organization 'apifactory' is configured with a base path /weather, then an API resource is any URI path that occurs after: apifactory-test.apigee.net/weather. For example, in the request path apifactory-test.apigee.net/weather/forecasts, /forecasts is an API resource.

API resources can be defined explicitly as URI fragments (for example, /forecasts, /reports, /blogs, /articles), or they can be defined using wildcards:

• /*: Defines a single URI level as wild card. For example, /forecast/* defines /forecast/toronto and /forecasts/newyork as valid URIs. This is often used to support IDs, for example, /reports/*/forecasts defines the following as valid URIs: /reports/toronto/forecasts and /reports/newyork/forecasts.
• /**: Defines all levels as wild cards. For example, /reports/** defines /reports/toronto/forecasts and /reports/newyork/forecasts as valid URIs.

Quota variables can be set as API Product attributes or as elements:

As attributes:

• developer.quota.limit
• developer.quota.interval
• developer.quota.timeunit (Supported values are second/minute/hour/day/month)

As elements:

• quota.limit
• quota.interval
• quota.timeunit (Supported values are second/minute/hour/day/month)

To further limit access to the URIs defined in an API proxy, you can optionally define:

• scopes: A comma-separated list of named scopes, which are validated at runtime against a list of scopes presented in the access token associated with an incoming request. A scope mismatch between API product configuration and access token contents results in an authorization failure.
• proxies: A comma-separated list of API proxies, the names of which derive from APIs listed in an organization. If proxies are specified, request made to the list API resource via API proxies other than those listed result in authorization failures. This feature is used to prevent URIs from being accidentally exposed by other API proxies in an organization.
• environments: A comma-separated list of environments. If environments are specified, requests made to API resources via API proxies deployed in environments other than those specified result in authorization failures. This feature is used to prevent access to production resources via APIs deployed test, for example.

Attributes can be used to set any arbitrary metadata that you need for monitoring or analytics.

Sample Request:

$ curl -H "Content-Type:application/json" -X POST -d \
 '{
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "division",
    "value" : "accounting"
  } ],
  "displayName" : "Sandbox Silver",
  "name" : "sandbox",
  "apiResources" : [ "/v2/**", "/v1/receiveSMS", "/v3/*/send" ],
  "description" : "Provides rate limited access to sandbox account APIs",
  "scopes": ["read", "write"],
  "environments": [ "test" ],
  "proxies": [ "MyAPI" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour"
}'  \
-u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts

Request Payload Elements:

Name	Description	Default	Required?
approvalType	Manual or Auto. If Manual, consumer key is generated and returned in 'pending' state. If manual consumer key generated and returned in 'Approved' state.	N/A	Yes
attributes	Arbitrary name/value pairs	N/A	No
displayName	The name to be displayed in the UI or developer portal to developers registering for API access	N/A	Yes
name	The internal name of the API Product	N/A	Yes
apiResources	A comma separated list of API resources to be bundled in the API Product.	N/A	Yes
scopes	A comma separated list of scopes. These must map to the scopes defined in an Oauth policy associated with the API Product. Any scope mismatch between an Acces Token presented and the API Product results in auth failure.	N/A	No
environments	A comma-separated list of environment name in an organization. Requests to environments not listed are rejected.	N/A	No
proxies	A comma-separated list of API proxy names in an organization. Requests to API proxies not listed are rejected.	N/A	No
quota	The number of request messages permitted by this API product.	N/A	Yes
quotaInterval	The time interval over which the number of request messages is calculated.	N/A	Yes
quotaTimeUnit	The time unit defined for the quotaInterval	N/A	Yes

Sample Response:

{
  "apiResources" : [ "/v2/**", "/v1/receiveSMS", "/v3/*/send" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "division",
    "value" : "accounting"
  } ],
  "createdAt" : 1360001831329,
  "createdBy" : "admin@apigee.com",
  "description" : "Provides rate limited access to sandbox account APIs",
  "displayName" : "Sandbox Silver",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1360001831329,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "sandbox",
  "proxies" : [ "MyAPI" ],
  "quota" : "10",
  "quotaInterval" : "2",
  "quotaTimeUnit" : "hour",
  "scopes" : [ "read", "write" ]
}

Response Payload Elements:

Name	Description
apiResources	A comma separated list of API resources to be bundled in the API Product.
approvalType	Manual or Auto. If Manual, consumer key is generated and returned in 'pending' state. If manual consumer key generated and returned in 'Approved' state.
attributes	Arbitrary name/value pairs
createdAt	UNIX time when the API Product was created
createdby	username of the user who created the API Product
displayName	The display name of the API Product, used in Apps that display the API Product to Developers Apigee
lastModifiedAt	UNIX time when the API Product was most recently updated
lastModifiedBy	Apigee username of the user who most recently updated the API Product
name	The internal name of the API Product
environments	A comma-separated list of environment name in an organization. Requests to environments not listed are rejected.
proxies	A comma-separated list of API proxy names in an organization. Requests to API proxies not listed are rejected.
quota	The number of request messages permitted by this API product.
quotaInterval	The time interval over which the number of request messages is calculated.
quotaTimeUnit	The time unit defined for the quotaInterval
scopes	A comma separated list of scopes. These must map to the scopes defined in an Oauth policy associated with the API Product. Any scope mismatch between an Acces Token presented and the API product results in authorization failure.

Errors

Failure 5xx with proper error message
{
   "Error":{
      "Code":"keymanagement.service.apiproduct_invalid_name",
      "Message":"Invalid ApiProduct Name",
      "Contexts":""
   }
}

Last updated: 23 days ago