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.

Edge

To access the API product bundles page using the Edge UI, select Publish > Monetization > Product Bundles in the left navigation bar.

As highlighted in the previous figure, the Product Bundles page enables you to:

View summary information for all product bundles including bundle name and the list of API products that it contains
Add a product bundle
Edit a product bundle
Search the list of product bundles on any visible field

You can manage the API products in a product bundle or delete a product bundle (if no rate plans are defined) using the API only.

Classic Edge (Private Cloud)

To access the API packages page using the Classic Edge UI, select Publish > Packages in the top navigation bar.

The API Packages page enables you to:

View summary information for all API packages including the API products it contains and the associated rate plans
Add an API package
Edit an API package
Add and manage rate plans
Toggle the rate plan access setting (public/private)
Filter the list of packages

You can manage the API products in an API package or delete an API package (if no rate plans are defined) using the API only.

Adding a product bundle

To add an API product bundle:

Click + API Product Bundle on the Product Bundles page.
Enter a name for the API product bundle.
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.
Repeat step 3 to add additional API product names.
For each API product that you add, configure the transaction recording policy.
Click Save Product Bundle.

Editing a product bundle

To edit a product bundle:

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

The product bundle panel is displayed.
Edit the product bundle fields, as required.

See configure the transaction recording policy for more information.
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:

Query Parameter	Description
`all`	Flag that specifies whether to return all API product bundles. If set to false, the number of API product bundles returned per page is defined by the `size` query parameter. Defaults to false.
`size`	Number of API product bundles returned per page. Defaults to 20. If the `all` query parameter is set to `true`, this parameter is ignored.
`page`	Number of the page that you want to return (if content is paginated). If the `all` query parameter is set to `true`, this parameter is ignored.

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:

Query Parameter	Description	Default
`current`	Flag that specifies whether to retrieve only active API product bundles (`current=true`) or all packages (`current=false`). All the rate plans in an active package are considered to be available.	`current=false`
`allAvailable`	Flag that specifies whether to retrieve all available API product bundles (`allAvailable=true`) or only API product bundles available specifically for the developer or company (`allAvailable=false`). All available refers to the API product bundles that are available to the specified developer or company in addition to other developers or companies. API product bundles available specifically to a company or developer only contain rate plans that are available exclusively to that company or developer.	`allAvailable=true`

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.

Note: If you have an API product bundle with draft rate plans defined, you must delete the draft rate plans before you can delete the API product bundle. See Deleting a rate plan draft using the API.

To ensure the integrity of transaction activity and reporting, you cannot delete or modify API product bundles after you have published a rate plan. An API product bundle represents a snapshot of the API product(s) they contain, and any subsequent updates to an API product are not reflected in an existing API product bundle. If you could modify or delete API product bundles with rate plans, especially when developers are currently signed up for those rate plans, it would be extremely difficult to reconcile past transactions against those changing API product bundles.

If you have an API product bundle with published rate plans, instead of deleting a package, you can let existing rate plans expire so that the API product bundles can no longer be used, or create new API product bundles and direct your developer community to start using those instead. By letting rate plans expire as a way of retiring API product bundles, you retain their transaction records.

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:

Name	Description	Default	Required?
`description`	A description of the API product bundle.	N/A	Yes
`displayName`	The name to display for the API product bundle (for example, in a catalog of API packages).	N/A	Yes
`name`	The name of the API product bundle.	N/A	Yes
`organization`	The organization that contains the API product bundle.	N/A	No
`product`	An array of one or more products in the API product bundle.	N/A	No
`status`	A status indicator for the API product bundle. The status indicator can have one of the following values: CREATED, ACTIVE, INACTIVE. Note: Currently, the status indicator value is maintained in the API product bundle, but it is not used.	N/A	Yes