APIs

You can retrieve the aggregated license usage data for a cluster from the last 24 months by using dedicated API calls. Additionally, you can use the APIs to retrieve License Service version and health.

Available APIs

Table 1. List of available APIs
API Description
Retrieving an audit snapshot Retrieve an audit snapshot that is needed to fulfill the requirements of Container Licensing rules.
Retrieving license usage of products Retrieve the list of products that are deployed on the cluster with their license usage. Use this API to integrate with external tools to monitor you license usage.
Retrieving license usage of bundled products Retrieve the list of bundled products that are deployed on the cluster with their license usage. Use this API to integrate with external tools to monitor you license usage.
Retrieving contribution of services Retrieve the contribution of services in the overall license usage of your bundled products. This information is additional and applies only to limited number of enabled products.
Retrieving information about License Service version Retrieve information about License Service version for troubleshooting or upgrade purposes.
Retrieving information about License Service health Retrieve information about License Service health to identify problems.

For an overview of all available APIs, see: License Service API schema.

Obtaining the License Service URL

To obtain the License Service URL that is required to retrieve license usage data from the cluster, complete the following steps:

  1. Open the OpenShift console and go to Networking > Routes.
  2. Set the project to All Projects.
  3. Find the ibm-licensing-service-instance route and copy the URL listed as Location. It is your License Service URL.

Note: Alternatively, you can use the following command to obtain the License Service URL: kubectl get routes -n <your-foundational-services-namespace> | grep ibm-licensing-service-instance | awk '{print $2}'. This command assumes that the IBM Cloud Pak foundational services are installed in foundational-services namespace. If your product installs foundational services in a different namespace, adjust the command.

You can use the License Service URL to access the simplified License Service interface for testing purposes. Paste the URL into your browser, select one of the APIs, and provide the authorization token. The interface is limited and retrieves the licensing data for last 30 days for all products.

API authentication

To use the License Service APIs, you need to authenticate first. To learn how to get the secure authentication token, see API authentication.

Retention period

You can use the APIs to retrieve the aggregated license usage for the last 24 months.

Time range

By default, each of the APIs retrieves data from the last 30 days. You can change that, by defining the startDate and endDate parameters.

Retrieving an audit snapshot

API URL

<License Service URL>/snapshot

API parameters

The following table provides the information about the API parameters to retrieve an audit snapshot:

Table 2. Information about API parameters to retrieve an audit snapshot
API Type Description
token String If you use the default authentication method, you need to specify the token parameter with the License Service API token in the API URL. For more information about how to retrieve the token, see Obtaining the License Service token.
startDate String Optional: Specify the start date in YYYY-MM-DD format. If you specify startDate, you must also set the endDate.
endDate String Optional: Specify the end date in YYYY-MM-DD format. If you specify endDate, you must also set the startDate.
metricName String Optional: Specify the name of the metric to retrieve the data of the parent IBM Cloud Paks or IBM Solution Bundle with the specified metricName. If the metricName is not specified, the API retrieves data of all parent IBM Cloud Paks or IBM Solution Bundle with the available metrics.
  • Example: Retrieving an audit snapshot for the specific period

    To retrieve an audit snapshot for the specific period, define the startDate and endDate parameters. The date should have the following format YYYY-MM-DD.

    • Using the License Service token:

    API URL:

    <License Service URL>/snapshot?token=<token>&startDate=<YYYY-MM-DD>&endDate=<YYYY-MM-DD>
    

    For example:

    https://ibm-licensing-service-instance-<your-foundational-services-namespace>.apps.hostname.example/snapshot?token=YourToken&startDate=2020-09-01&endDate=2020-09-30
    
    • Using the Service account token:

    API URL:

    <License Service URL>/snapshot?startDate=<YYYY-MM-DD>&endDate=<YYYY-MM-DD>
    

    For example:

    https://ibm-licensing-service-instance-<your-foundational-services-namespace>.apps.hostname.example/snapshot?startDate=2020-09-01&endDate=2020-09-30
    

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves a license usage snapshot for your cluster. An audit snapshot is a compressed .zip package that includes a complete set of audit documents that certify your license usage per cluster.

To view a list of files that are included in an audit snapshot, see Content of the audit snapshot.

Integrating with the audit snapshot

To integrate with the audit snapshot, use the names of the columns from the .csv files as the point of reference, not the column order. The names of the columns are fixed. However, the order of the columns might change.

Retrieving license usage of products

API URL

<License Service URL>/products

API parameters

The following table provides information about the API parameters to retrieve the license usage of IBM Cloud Paks and IBM Certified Containers:

Table 3. Information about API parameters to retrieve the license usage of IBM Cloud Paks and IBM Certified Containers
API Type Description
token String If you use the default authentication method, you need to specify the token parameter with the License Service API token in the API URL. For more information about how to retrieve the token, see Obtaining the License Service token.
startDate String Optional: Specify the start date in YYYY-MM-DD format. If you specify startDate, you must also set the endDate.
endDate String Optional: Specify the end date in YYYY-MM-DD format. If you specify endDate, you must also set the startDate.
metricName String Optional: Specify the name of the metric to retrieve the data of the parent IBM Cloud Paks or IBM Solution Bundle with the specified metricName. If the metricName is not specified, the API retrieves data of all parent IBM Cloud Paks or IBM Solution Bundle with the available metrics.
groupName String Optional: Specify the name of the reporting group to retrieve the data of the products with the specified groupName.
format String Optional: The output is displayed in JSON format as default. To download the output in csv format, set the format parameter to csv.

For more information about the API parameters and how to use them, see License Service API schema.

API description

  • This API call retrieves information about the products that are deployed on a cluster with the value and date of the license usage peak. By default, the retrieved data includes information about your product, all IBM Cloud Paks, or stand-alone containerized products that are deployed on a cluster.

  • This API call retrieves information about the products that are deployed in namespaces that belong to user-defined groups. To filter the data by group use the groupName parameter: <License Service URL>/products?groupName=<groupName>. To enable this feature, see Filtering the license usage data by user-defined groups.

This API retrieves the following information per product:

Table 4. Information about each product
API Description
name The name of the product.
id The identifier of the product.
metricPeakDate The date when the license metric usage of the product was the highest within the requested period.
metricQuantity The highest number of license units that the product used within the requested period.
metricName The list of metrics of the parent IBM Cloud Paks or IBM Solution Bundle.

Retrieving license usage of bundled products

API URL

<License Service URL>/bundled_products

API parameters

The following table provides information about the API parameters to retrieve the license usage of the bundled products:

Table 5. Information about API parameters to retrieve the license usage of the bundled products
API Type Description
token String If you use the default authentication method, you need to specify the token parameter with the License Service API token in the API URL. For more information about how to retrieve the token, see Obtaining the License Service token.
startDate String Optional: Specify the start date in YYYY-MM-DD format. If you specify startDate, you must also set the endDate.
endDate String Optional: Specify the end date in YYYY-MM-DD format. If you specify endDate, you must also set the startDate.
metricName String Optional: Specify the name of the metric to retrieve the data of the parent IBM Cloud Paks or IBM Solution Bundle with the specified metricName. If the metricName is not specified, the API retrieves data of all parent IBM Cloud Paks or IBM Solution Bundle with the available metrics.
groupName String Optional: Specify the name of the reporting group to retrieve the data of the products with the specified groupName.
format String Optional: The output is displayed in JSON format as default. To download the output in csv format, set the format parameter to csv.

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves information about the bundled products that are included in IBM Cloud Paks that are deployed on a cluster with the highest license usage within the requested period.

This API retrieves the following information per each bundled product:

Table 6. Information of each bundled product
API Description
productName The name of the detected bundled product.
productId The identifier of the bundled product.
metricName The list of metrics of the parent IBM Cloud Paks or IBM Solution Bundle.
metricPeakDate The date when the license usage of the bundled product was the highest within the requested period.
metricMeasuredQuantity The highest number of license units that the bundled product used within the requested period.
cloudpakId The identification number of the IBM Cloud Pak® to which the program is bundled.
cloudpakVersion Version of the IBM Cloud Pak® to which the program is bundled.
cloudpakMetricName The license metric unit that is used by the entire IBM Cloud Pak® to which the bundled product contributes.
metricConversion The ratio that shows how the license usage of the bundled product is counted when compared with the license usage of the IBM Cloud Pak®. It shows how the program's license metrics are recalculated when compared to the IBM Cloud Pak® license metrics.
metricConvertedQuantity The number of license units that the bundled product contributed to the overall license usage of the IBM Cloud Pak®. The value is calculated by comparing metricMeasuredQuantity against metricConversion.

Retrieving contribution of services

This API is available from IBM Cloud Pak foundational services version 3.19.x.

API URL

<License Service URL>/services

API parameters

The following table provides information about the API parameters to retrieve the license metric contribution of the services:

Table 7. Information about API parameters to retrieve the license metric contribution of the services
API Type Description
token String If you use the default authentication method, you need to specify the token parameter with the License Service API token in the API URL. For more information about how to retrieve the token, see Obtaining the License Service token.
startDate String Optional: Specify the start date in YYYY-MM-DD format. If you specify startDate, you must also set the endDate.
endDate String Optional: Specify the end date in YYYY-MM-DD format. If you specify endDate, you must also set the startDate.
metricName String Optional: Specify the name of the metric to retrieve the data of the parent IBM Cloud Paks or IBM Solution Bundle with the specified metricName. If the metricName is not specified, the API retrieves data of all parent IBM Cloud Paks or IBM Solution Bundle with the available metrics.
groupName String Optional: Specify the name of the reporting group to retrieve the data of the products with the specified groupName.
format String Optional: The output is displayed in JSON format as default. To download the output in csv format, set the format parameter to csv.

For more information about the API parameters and how to use them, see License Service API schema.

API description

This API call retrieves information about how the usage of services contributes to the overall license usage of the bundled products under which these services are grouped. This information might give you a better understanding of your license usage, however, it is not obligatory from the Container Licensing rules perspective.

You can use this API to retrieve information only for the products that have three-layer reporting structure that includes services that are grouped under bundled products, and are enabled for reporting, such as IBM Cloud Pak for Data.

This API retrieves the following information:

Table 8. Information of the product with three-layer reporting structure
API Description
cloudpakId The identifier of the Cloud Pak with which the bundled product and its services are deployed.
cloudpakMetricName The license metric unit that is used by the product.
productName The name of the bundled product.
productId The identifier of the bundled product.
metricName The list of metrics of the parent IBM Cloud Paks or IBM Solution Bundle.
serviceName The name of the service that is deployed under the bundled product.
serviceId The identifier of the service.
serviceMetricValue The highest number of license units that the service used that contributed to the overall license usage of its bundled product.
metricDate The date when the license metric usage of the product was the highest within the requested period.

Retrieving information about License Service version

API URL

<License Service URL>/version

API description

This API call retrieves the following information about the License Service version:

Table 9. License service version information
API Description
version The version of License Service that is deployed on a cluster.
buildDate The buildDate identifies the image that was used to deploy License Service and might be needed for support purposes.
commit The commit ID identifies the image that was used to deploy License Service and might be needed for support purposes.

Retrieving information about License Service health

API URL

<License Service URL>/health

API parameters

  • Required: If you use the default authentication method, the License Service token, you need to provide the token parameter in the API URL. For more information about how to retrieve the token, see Obtaining the License Service token.

API description

This API call retrieves the following information:

Table 10. License Service health information
API Description
count The number of pods that are deployed on the cluster but have incomplete or improper product annotations. Improper annotations result in the license usage of a product not being measured. The annotations include the product metadata, such as the product ID and metric, and are implemented by the IBM team that develops the product to enable license usage measurements.
pods The list of pods that that have improper annotations.