Managing API product bundles

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

Bundle one or more API products into a single monetized container, referred to as an API product bundle, as described in the following sections.

What is an API product bundle?

An API product bundle is a collection of API products that is presented to developers as a group, and typically associated with one or more rate plans for monetization. You can create multiple API product bundles and include one or more API products in each. You can put the same API product or products in different bundles and associate them with different (or the same) rate plans.

Developers can register their apps to use an API product bundle only by purchasing one of the rate plans currently in effect. An API product bundle does not become visible to developers until you add and publish (as public) a rate plan for the product bundle (with a start date of the current date or a future date), as described in Managing rate plans. After you add and publish a rate plan, developers logging into your developer portal will be able to select the API product bundle and choose the rate plan. Alternatively, you can accept a rate plan for a developer using the management API. For more information, see Purchase published rate plans using the API.

After you add an API product to an API product bundle, you may need to set up price points for the API product. You need to do this only if all of the following are true:

• You set up a revenue sharing rate plan for the API product.
• Developers charge third parties for the use of resources in the API product.
• There is a minimum or maximum restriction on the amount developers can charge, and you want to notify developers of the restriction.

The minimum and maximum prices are displayed in the details for the API product bundle.

Exploring the Product Bundles page

Access the Product Bundles page, as described below.

Adding a product bundle

To add an API product bundle:

1. Click + API Product Bundle on the Product Bundles page.
2. Enter a name for the API product bundle.

3. Enter the name of an API product in the Add a Product field.

   As you type the name of an API product, a list of API products that contain the string displays in a drop-down. Click the name of an API product to add it to the bundle. Repeat to add additional API products.

4. Repeat step 3 to add additional API product names.
5. For each API product that you add, configure the transaction recording policy.
6. Click Save Product Bundle.

Editing a product bundle

To edit a product bundle:

1. On the Product Bundles page, click within the row of the product bundle that you want to edit.

   The product bundle panel is displayed.

2. Edit the product bundle fields, as required.

   See configure the transaction recording policy for more information.

3. Click Update Product Bundle.

Managing API product bundles using the API

The following sections describe how to manage API product bundles using the API.

Creating an API product bundle using the API

To create an API product bundle, issue a POST request to /organizations/{org_name}/monetization-packages. When you issue the request, you must:

• Identify the API products to include in the API product bundle.
• Specify a name and description for the API product bundle.
• Set a status indicator for the API product bundle. The status indicator can have one of the following values: CREATED, ACTIVE, INACTIVE. Currently, the status indicator value you specify is maintained in the API product bundle, but it is not used for any purpose.

Optionally, you can specify the organization.

See API product bundle configuration properties for a list of options exposed to the API.

For example:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "description": "payment messaging package",
     "displayName": "Payment Messaging Package",
     "name": "Payment Messaging Package",
     "organization": { "id": "{org_name}" },
     "product": [
       { "id": "messaging" },
       { "id": "payment" }
     ],
     "status": "CREATED"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \
-u email:password

The following provides an example of the response:

{
   "description" : "payment messaging package",
   "displayName" : "Payment Messaging Package",
   "id" : "payment_messaging_package",
   "name" : "Payment Messaging Package",
   "organization" : {
     "id" : "{org_name}",
     "separateInvoiceForFees" : false
   },
   "product" : [ {
     "customAtt1Name" : "user",
     "description" : "Messaging",
     "displayName" : "Messaging",
     "id" : "messaging",
     "name" : "messaging",
     "organization" : {
       "id" : "{org_name}",
       "separateInvoiceForFees" : false
     },
     "status" : "CREATED"
   }, {
     "customAtt1Name" : "user",
     "description" : "Payment",
     "displayName" : "Payment",
     "id" : "payment",
     "name" : "payment",
     "organization" : {
       "id" : "{org_name}",
       "separateInvoiceForFees" : false
     },
     "status" : "CREATED"
   }],
   "status" : "CREATED"
 }

Notice that the response includes additional information about the API products and any custom attributes specified for those API products. (Custom attributes are specified when you create an API product.) Custom attributes for an API product can be factored into various rate plans. For example, if you set up a rate card plan, where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction.

Managing the API products in an API product bundle using the API

You can add or delete an API product from an API product bundle using the API, as described in the following sections.

Adding an API product to an API product bundle

To add an API product to an API product bundle, issue a POST request to organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, where {org_name} specifies the name of your organization, {package_id} specifies the API product bundle name, and {product_id} specifies the ID of the API product.

For example:

$ curl -H "Accept:application/json" -X POST -d \
'{}'\
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Adding an API product to an API product bundle with API product-specific rate plans

To add an API product to an API product bundle that has one or more API product-specific rate plans defined (rate card or revenue share), issue a POST request to organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, where {org_name} specifies the name of your organization, {package_id} specifies the API product bundle name, and {product_id} specifies the ID of the API product.

You must pass the rate plan details for the new API product in the request body. Except for the ratePlanRates array, the rate plan values must match those specified for all other API products. For more information about the rate plan attributes that can be defined, see Configuration properties for rate plans.

For example:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "ratePlan": [ 
        {
            "id": "mypackage_rateplan1",
            "ratePlanDetails": [
                {
                    "currency": {
                        "id": "usd"
                    },
                    "duration": 1,
                    "durationType": "MONTH",
                    "meteringType": "UNIT",
                    "organization" : {
                        "id": "{org_name}",
                    "paymentDueDays": "30",
                    "ratePlanRates": [
                        {
                            "rate": "1.99",
                            "startUnit": "0",
                            "type": "RATECARD"
                        }
                    ],
                    "ratingParameter": "VOLUME",
                    "type": "RATECARD"
                }
            ]
        }
    ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Deleting an API product from an API product bundle

To delete an API product from an API product bundle, issue a DELETE request to the organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}, where {org_name} specifies the name of your organization, {package_id} specifies the API product bundle name, and {product_id} specifies the ID of the API product.

For example:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}/products/{product_id}" \
-u email:password

Viewing API product bundles using the API

You can retrieve a specific API product bundle or all API product bundles in an organization. You can also retrieve API product bundles that have transactions in a given date range, that is, only packages for which users invoke apps that access APIs in those packages within a specified start and end date.

Viewing a specific API product bundle: To retrieve a specific API product bundle, issue a GET request to /organizations/{org_name}/monetization-packages/{package_id}, where {package_id} is the identification of the API product bundle (the ID is returned in the response when you create the API product bundle). For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment_messaging_package" \
-u email:password

Viewing all API product bundles: To retrieve all API product bundles for an organization, issue a GET request to /organizations/{org_name}/monetization-packages. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages" \
-u email:password

You can pass the following query parameters to filter the results:

The response for viewing all API product bundles in an organization should look like this (only part of the response is shown):

{
  "monetizationPackage" : [ {
    "description" : "payment messaging package",
    "displayName" : "Payment Messaging Package",
    "id" : "payment_messaging_package",
    "name" : "Payment Messaging Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Messaging",
      "displayName" : "Messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    }, {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "Communications",
    "displayName" : "Communications",
    "id" : "communications",
    "name" : "Communications",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Location",
      "displayName" : "Location",
      "id" : "location",
      "name" : "location",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    }, {
      "customAtt1Name" : "user",
      "description" : "Messaging",
      "displayName" : "Messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "Payment",
    "displayName" : "Payment",
    "id" : "payment",
    "name" : "Payment",
    "organization" : {
     ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED"
    } ],
    "status" : "CREATED"
  } ],
  "totalRecords" : 3
}

Viewing API product bundles with transactions: To retrieve API product bundles with transactions in a given date range, issue a GET request to /organizations/{org_name}/packages-with-transactions. When you issue the request, you need to specify as query parameters a start date and end date for the date range. For example, the following request retrieves API product bundles with transactions during the month of August, 2013.

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/packages-with-transactions?START_DATE=2013-08-01&END_DATE=2013-08-31" \
-u email:password

The response should look something like this (only part of the response is shown):

{
  "monetizationPackage" : [ {
    "description" : "Payment Package",
    "displayName" : "Payment Package",
    "id" : "payment_package",
    "name" : "Payment Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "customAtt2Name" : "response size",
      "customAtt3Name" : "content-length",
      "description" : "payment api product",
      "displayName" : "payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "status == 'SUCCESS'"
    } ],
    "status" : "CREATED"
  }, {
    "description" : "messaging package",
    "displayName" : "Messaging Package",
    "id" : "messaging_package",
    "name" : "Messaging Package",
    "organization" : {
      ...
    },
    "product" : [ {
      "customAtt1Name" : "user",
      "customAtt2Name" : "response size",
      "customAtt3Name" : "content-length",
      "description" : "messaging api product",
      "displayName" : "messaging",
      "id" : "messaging",
      "name" : "messaging",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "status == 'SUCCESS'"
    } ],
    "status" : "CREATED"
  },
     ...
  } ]
}

Viewing API product bundles accepted by a developer or company using the API

View the API product bundles accepted by a specific developer or company by issuing a GET request to the following APIs, respectively:

• /organizations/{org_name}/developers/{developer_id}/monetization-packages, where {developer_id} is the ID (email address) of the developer.
• /organizations/{org_name}/companies/{company_id}/monetization-packages, where {company_id} is the ID of the company.

When you issue the request, you can optionally specify the following query parameters:

For example, the following request retrieves all API product bundles accepted by a specific developer:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev1@myorg.com/monetization-packages" \
-u email:password

The following request retrieves only active API packages accepted by a specific company:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/myCompany/monetization-packages?current=true" \
-u email:password

Deleting an API product bundle using the API

You can delete an API product bundle only if it does not have any rate plans defined.

To delete an API product bundle that does not have any rate plans defined, issue a DELETE request to organizations/{org_name}/monetization-packages/{package_id}, where {org_name} specifies the name of your organization and {package_id} specifies the API product bundle name.

For example:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/{package_id}" \
-u email:password

API product bundle configuration properties for the API

The following API product bundle configuration options are exposed to the API: