APIs for retrieving License Service data

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

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 ibm-common-services | grep ibm-licensing-service-instance | awk '{print $2}'. This command assumes that the IBM Cloud Pak foundational services are installed in ibm-common-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.

Retrieving an audit snapshot

API URL

<License Service URL>/snapshot

API parameters

• Optional: startDate, endDate, metricName

• 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.

• 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-ibm-common-services.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-ibm-common-services.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

• Optional: startDate, endDate, format, metricName, groupName
• 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.

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:

Retrieving license usage of bundled products

API URL

<License Service URL>/bundled_products

API parameters

• Optional: startDate, endDate, format, metricName, groupName
• 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.

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:

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

• Optional: startDate, endDate, format, metricName
• 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.

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:

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:

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: