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
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:
- Open the OpenShift console and go to Networking > Routes.
- Set the project to All Projects.
- 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:
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
andendDate
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:
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:
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:
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:
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:
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:
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:
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:
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. |