Using Public APIs

The Application Programming Interfaces (APIs) are provided as Representational State Transfer (RESTful) web services. You can access these services using clients implemented in any programming language that supports the HTTP protocol. BMC Helix Capacity Optimization provides REST API endpoints to perform all tasks that are currently supported by the application. These REST API endpoints are documented in the OpenAPI UI.

Accessing the OpenAPI host for APIs

  1. In BMC Helix Portal, go to Common Services > User Management.
  2. Create an API user
    Use the secret key to authenticate yourself before you run an endpoint. 
  3. From a supported browser, enter the following URL to access the API documentation in OpenAPI:
    https://<host name>/opt/api/<service-name>/openapi.yaml 
    For example, to access the catalog API, enter https://<host name>/opt/api/catalog/openapi.yaml 
  4. In the OpenAPI UI, you can access, test, and execute any APIs supported by the service.

Agent Data API

Contains APIs for the Agent data.

URL to access: https://<host name>/opt/api/agentdata/openapi.yaml 

API callDescription
GET/opt/api/v1/agentdata/aboutReturns the status of the agent data service. 
POST /opt/api/v1/agentdata/gwsrequestCreates a Gateway Server for the specified request.
PUT /opt/api/v1/agentdata/gwsrequestUpdates the details of the specified Gateway Server ID.
GET /opt/api/v1/agentdata/gwsrequest/{gws_id}Retrieves the Gateway Server details for the specified Gateway Server ID.
POST /opt/api/v1/agentdata/data Retrieves the data points for a specific set of entities.

Analysis API

URL to access: https://<host name>/opt/api/analysis/openapi.yaml 

API callDescription
Execute API
GET /opt/api/v1/analysis/aboutReturns the status of the analysis service. 
POST /opt/api/v1/analysis/executeExecutes an analysis and returns the results synchronously. 
POST/opt/api/v1/analysis/execute_asyncExecutes an analysis and returns the results asynchronously. 
GET /opt/api/v1/analysis/executions/{execution_id}Retrieves the status of an analysis execution.
GET/opt/api/v1/analysis/executionsRetrieves the recent execution results for the current user.
GET/opt/api/v1/analysis/executions/tag/{external_group_id}Retrieves the list of all executions with the specified tag.
GET/opt/api/v1/analysis/executions/{type}/{id}Retrieves the details of all analysis or models with the specified plot ID.
Results API
GET/opt/api/v1/analysis/results/{type}/{id}/chart/{chart_id}Retrieves the chart details.
GET/opt/api/v1/analysis/entity_filter/{id}Retrieves the list of entities for the specified entity ID.
POST/opt/api/v1/analysis/entity_filterRetrieves the list of entities.
Threshold API
POST/opt/api/v1/analysis/threshold/{structure_id}Retrieves thresholds for the specified entity IDs and metrics.

Catalog API

The Catalog REST API is used to view the status of the tenants and the lookup fields.

URL to access: https://<host name>/opt/api/catalog/openapi.yaml 

API call

Description

Tenants API
GET/opt/api/v1/catalog/aboutReturns the status of the catalog service. 

POST/opt/api/v1/catalog/tenants/activation

Creates the required index and index mapping for the tenant activation.

DELETE /opt/api/v1/catalog/tenants/deactivation

Deactivates the tenant and removes the associated mappings and documents.
Lookup API
GET/opt/api/v1/catalog/lookup/{entityId}Retrieves all lookup entries for the specified entity.

PATCH /opt/api/v1/catalog/lookup/{entityId}/add

Adds the specified set of lookup fields.

DELETE /opt/api/v1/catalog/lookup/{entityId}/remove

Deletes the specified set of lookup fields

POST /opt/api/v1/catalog/lookup/bycatalog/{entityCatalogId}

Creates a shared lookup catalog with filtering options by provider_id.

POST /opt/api/v1/catalog/lookup

Creates an entity in the catalog, if the entity does not exist.

POST /opt/api/v1/catalog/lookup/sequences

Searches for lookup sequences based on the specified set of mandatory filters on entity IDs and lookup sequences.
Entities API

POST/opt/api/v1/catalog/entities

Creates a new entity.
GET/opt/api/v1/catalog/entities/{entityId}Retrieves all entities by their entity ID.

PUT/opt/api/v1/catalog/entities/{entityId}

Updates an entity for the specified entity ID.

DELETE /opt/api/v1/catalog/entities/{entityId}

Deletes the entity for the specified ID.

POST /opt/api/v1/catalog/entities/{entityId}/resources

Creates a resource for the specified entity ID.

PATCH /opt/api/v1/catalog/entities/{entityId}/resources

Adds a resource.
GET /opt/api/v1/catalog/entities/{entityId}/resourcesRetrieves all resources for the entity ID.

DELETE /opt/api/v1/catalog/entities/{entityId}/resources

Deletes all resources and metrics for the specified entity ID.

POST /opt/api/v1/catalog/entities/{entityId}/resources/update

Updates the resources.
GET /opt/api/v1/catalog/entities/{entityId}/resources/{resourceId}Retrieves all resources for the resource ID.

PUT /opt/api/v1/catalog/entities/{entityId}/resources/{resourceId}

Updates the resource by ID.

DELETE /opt/api/v1/catalog/entities/{entityId}/resources/{resourceId}

Deletes all resources for a resource ID.

POST /opt/api/v1/catalog/entities/resources/metric-activity

Retrieves the metric activity details for the specified set of metrics.

POST /opt/api/v1/catalog/entities/resources/{resourceId}/metric-activity

Updates the metric activity for a resource.

POST /opt/api/v1/catalog/entities/resources/{resourceId}/metric-activity/bulk

Updates the metric activity for a resource in bulk.

POST /opt/api/v1/catalog/entities/relations

Retrieves the parent/child relations linked to a set of entities.

POST /opt/api/v1/catalog/entities/{entityId}/relations

Creates a relation.
GET /opt/api/v1/catalog/entities/{entityId}/relationsRetrieves all relations for an entity ID.

DELETE /opt/api/v1/catalog/entities/relations/bulk

Deletes all relations for an entity ID in bulk.
Explore API
GET /opt/api/v1/catalog/explore/domains/{domainId}/treeExplores domain relations for a specific domain.
GET /opt/api/v1/catalog/explore/entities/{entityId}/treeExplores entities relations for a specific domain.

POST /opt/api/v1/catalog/explore/entities/{entityId}/tree

Explores entities relations for a specific domain by applying filters.
Metrics API

POST /opt/api/v1/catalog/metrics/last

Retrieves configuration data for last (current) values.

DELETE /opt/api/v1/catalog/metrics/last

Deletes configuration data for last (current) values.

POST /opt/api/v1/catalog/metrics/last/bulk

Deletes configuration data for last (current) values in bulk.
Search API

POST /opt/api/v1/catalog/search

Searches the catalog resources.

POST /opt/api/v1/catalog/search/free

Searches the catalog resources with free search text capabilities.

POST /opt/api/v1/catalog/search/light

Searches the catalog resources and lists IDs associated with a given search.

POST /opt/api/v1/catalog/search/light/free

Searches the catalog resources with free search text capabilities and lists IDs associated with a given search.
RBAC API

POST/opt/api/v1/catalog/rbac/domains/configuration

Updates the groups for the specified domains.

PUT/opt/api/v1/catalog/rbac/domains/configuration

Adds the groups to the specified domains.

DELETE/opt/api/v1/catalog/rbac/domains/configuration

Deletes the groups from the specified domains.
GET/opt/api/v1/catalog/rbac/domains/configurationRetrieves the list of domains on which visibility privileges are set for the specified group.
GET /opt/api/v1/catalog/rbac/domains/configuration/{requestId}/statusRetrieves the status of the RBAC configuration request.
Entity tag API
GET /opt/api/v1/catalog/entities/tags/typesRetrieves the list of available tag types.

POST/opt/api/v1/catalog/entities/tags/types

Retrieves the list of available tag types by entity ID.

POST/opt/api/v1/catalog/entities/tags

Retrieves the list of available tag types and entity IDs.

POST/opt/api/v1/catalog/entities/{entityId}/tags

Adds tags to the specified entities

PATCH/opt/api/v1/catalog/entities/{entityId}/tags

Updates the specified set of tags for given entity.

DELETE/opt/api/v1/catalog/entities/{entityId}/tags

Deletes the specified set of tags for given entity.

Forecast API

Contains APIs for managing forecasts.

URL to access: https://<host name>/opt/api/forecast/openapi.yaml 

API call

Description

GET  /opt/api/forecast/aboutReturns the status of the forecast service.
POST /opt/api/v2/forecast/predictionUploads the data series prediction values.
POST /opt/api/v2/forecast/time_predictionUploads the time series prediction values.
POST /opt/api/v2/forecast/regressionUploads the data series regression values.
POST/opt/api/v2/forecast/time_regressionUploads the time series regression values.
POST/opt/api/v2/forecast/correlationUploads the correlation analysis values.
POST/opt/api/v2/forecast/extrapolationUploads the data series extrapolation values.
POST/opt/api/v2/forecast/costUploads the forecast costs for the next 12 months based on the aggregated data series.

Historical Time Series Ingestion API

Contains APIs for managing historical time series ingestion.

URL to access: https://<host name>/opt/api/htsingest/openapi.yaml 

API callDescription
GET/opt/api/htsingest/aboutReturns the status of the historical time series ingestion service.
POST/opt/api/v1/htsingest/relationsUploads an object relation file archive for processing.
POST /opt/api/v1/htsingest/tagsUploads object tags for processing.
POST /opt/api/v1/htsingest/timeseriesUploads time series for the specified entity.
POST/opt/api/v1/htsingest/timeseries/bulkUploads time series for the specified entity in bulk.
POST /opt/api/v1/htsingest/timeseries/{resid}Uploads time series for a specified resource ID.

Recommendation API

Contains APIs for managing the recommendations.

URL to access: https://<host name>/opt/api/optimizer/openapi.yaml 

API call

Description

GET/opt/api/optimizer/aboutReturns the status of the recommendation service. 
POST/opt/api/v1/optimizer/recommendationsGenerates recommendations.
POST/opt/api/v1/optimizer/rules/processProcesses the rules.
GET/opt/api/v1/optimizer/recommendations/entities/{entity_id}Retrieves the recommendations that are generated for a specific entity.
POST/opt/api/v1/optimizer/recommendations/searchReturns the recommendations that match the search criteria.

Data Provider API

Contains the APIs for managing the Data mart and View definition.

https://<host name>/openapi/datamart

https://<host name>//openapi/view

The following table provides the details of the Data Provider API methods:

API call

Description

Data mart API
GET/opt/api/datamarts/aboutStatus of the datamart service.
GET/opt/api/v1/datamartservice/datamartsRetrieves the list of data mart definitions according to the specified ownership.
POST /opt/api/v1/datamartservice/datamarts/{erid}/dataCreates a datamart with data for the specified datamart ID.
GET/opt/api/v1/datamartservice/datamarts/{erid}/metadataRetrieves the list of data marts for the specific datamart ID.
POST /opt/api/v1/datamartservice/datamarts/exports/excelExports the data marts to Excel.
POST /opt/api/v1/datamartservice/datamarts/{erid}/aggregatedataCreates a datamart with aggregated data for the specified datamart ID.
POST /opt/api/v1/datamartservice/datamarts/{erid}Creates a datamart for the specified datamart ID.
POST /opt/api/v1/datamartservice/datamarts/{erid}/filters/{filtername}Creates a datamart for the specified filter name.
View definition API
GET/opt/api/v1/viewdefinition/view

Retrieves a list of all capacity views in BMC Helix Capacity Optimization.

GET/opt/api/v1/viewdefinition/view/{viewid}/export

Exports the configuration of the selected view in file format (.viewpkg).

POST /opt/api/v1/viewdefinition/view/import


Imports a capacity view from another environment.

The request includes the name of the export file in the format: <view name_date of export>.viewpkg.

Pricing API

Contains the APIs for managing the pricing.

https://<host name>/openapi/pricing

API callDescription
AWS Reserved Price Controller API
GET /api/aboutRetrieves the status of the Pricing service.
GET /api/v1/providers/1/regions/{region_code}/reserved_instanceReturns the on-demand and effective hourly rate for standard EC2 reserved instances.
GET/api/v1/providers/1/ri_eligible_hoursRetrieves the eligible usage hours for AWS reserved instances.
GET /api/v1/providers/1/ri_normalization_factorsRetrieves the normalization factors for reserved instances for a specific provider.
GET  /api/v1/providers/1/sku_os_mapRetrieves the SKU to OS mappings.
Instances Size Pricing API
GET /api/v1/providers/{providerid}/regions/{region_code}/instance_size/{instance_type}Retrieves the instances size for a specific instance type.
Instances Pricing Controller API
GET/api/v1/providers/{providerid}/regions/{region_code}/cheapest_instanceRetrieves the cheapest compute and storage instances in a specific region that matches the given resources.
GET /api/v1/providers/{providerid}/regions/{region_code}/instance_familiesRetrieves the available instance families for a specific provider within a region.
GET /api/v1/providers/{providerid}/regions/{region_code}/instance_typesRetrieves a list of instance types for a specific provider within a region.
GET/api/v1/providers/{providerid}/regions/{region_code}/instance_types/{instance_type_id}Retrieves the 30 days instance type price for a monthly usage on-demand and for each reservation period (1 year, 3 years) where reservation payment option is standard, All, Upfront.
GET /api/v1/providers/{providerid}/regions/{region_code}/instance_types/{instance_type_id}/license_typesRetrieves the list of license types available for a specific instance type within a region.
License Types Pricing API
GET /api/v1/providers/{providerid}/license_typeRetrieves a license type that matches either a list of SKUs or a product description.
Normalization Factors Pricing API
GET/api/v1/providers/{providerid}/normalization_factorsRetrieves the compute normalization factors for a specific provider for all the instance types.
Pricing API for regions
GET/api/v1/providers/{providerid}/default_regionRetrieves the default region for the specified provider.
GET /api/v1/providers/{providerid}/regionsRetrieves the available regions for the specified provider.
GET /api/v1/providers/{providerid}/regions/{region_code}Retrieves the details of a region for the specified provider.
Simulation Pricing API
POST/api/v1/simulationRetrieves the cheapest compute and storage instances in a specific region that matches the given resources.
Storage Pricing API
GET/api/v1/providers/{providerid}/regions/{region_code}/storage_typesRetrieves the storage types for the specified provider ID and the region code.
GET/api/v1/providers/{providerid}/regions/{region_code}/storage_types/{storage_id}Retrieves the storage types for the specified provider ID, region code, and storage ID.
POST /api/v1/providers/{providerid}/regions/{region_code}/storage_types/{storage_id}/costRetrieves the 30 days cost for the specified storage type.
GET/api/v1/providers/{providerid}/storage/default_transaction_unitsRetrieves the default transaction units for the specified provider.

Backend Control API

The Backend Control API enables you to remotely manage and control the interactions with the backend components of BMC Helix Capacity Optimization.

 API methods

Executing a task/ETL

Method

POST

URI

https://<optapi external address>/dh-services/backend/requestTaskExecution

Request parameters

NA

Sample request

<?xml version="1.0" encoding="UTF-8"?>
<TaskExecutionRequest>
  <taskid>38</taskid>
  <request>RUN</request>
</TaskExecutionRequest>

Request status

Possible values: OK, ERROR, WARNING

Sample response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TaskExecutionRequestStatus>
    <taskexecreqid>21359</taskexecreqid>
    <requestStatus>OK</requestStatus>
</TaskExecutionRequestStatus>

Checking the execution status of a task or ETL.

Method

GET

URI

https://<optapi external address>/dh-services/backend/checkTaskExecutionStatus/<taskexecreqid>

Where taskexecreqid is the value obtained from the output of the /dh-services/backend/requestTaskExecution call.

Request parameters

NA

Sample request

NA

Sample response

Possible values: FINISHED, FAILED, TIMED_OUT, RUNNING, NO_STATUS

Submitting the execution report

Method

POST

URI

https://<optapi external address>/dh-services/backend/submitReportExecution/<report_id>

Request parameters

NA

Sample request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TaskExecutionRequestStatus>
    <taskexecreqid>21360</taskexecreqid>
    <requestStatus>OK</requestStatus>
</TaskExecutionRequestStatus>

 

Request status

Possible values: OK, ERROR, WARNING

Sample response

Possible values: OK, ERROR, and WARNING

Check the status of execution report

Method

GET

URI

https://<optapi external address>/dh-services/backend/checkReportExecutionStatus/<taskexecreqid>

Where taskexecreqid is the value obtained from the output of the /dh-services/backend/submitReportExecution/<report_id> call.

Request parameters

NA

Sample request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReportExecutionResults>
    <overallStatus>GENERATED</overallStatus>
    <ReportExecution>
        <status>GENERATED</status>
        <rundate>2016-09-12T00:00:00.000-04:00</rundate>
        <reportId>15</reportId>
        <Results>/cpitrep/reports/15/report_15_1473754939852/Diagnostic%20-%20Data%20Flow%20and%20Statistics.pdf</Results>
    </ReportExecution>
</ReportExecutionResults>

Request status

Possible values: GENERATED, FAILED, RUNNING, NO_STATUS

Sample response

Possible values: GENERATED, FAILED, RUNNING, NO_STATUS

Activate the ETL

Method

POST

URI

https://<optapi external address>/dh-services/backend/checkReportExecutionStatus/<taskexecreqid>

Where taskexecreqid is the value obtained from the output of the /dh-services/backend/submitReportExecution/<report_id> call.

Request parameters

NA

Sample request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ReportExecutionResults>
    <overallStatus>GENERATED</overallStatus>
    <ReportExecution>
        <status>GENERATED</status>
        <rundate>2016-09-12T00:00:00.000-04:00</rundate>
        <reportId>15</reportId>
        <Results>/cpitrep/reports/15/report_15_1473754939852/Diagnostic%20-%20Data%20Flow%20and%20Statistics.pdf</Results>
    </ReportExecution>
</ReportExecutionResults>

Request status

Possible values: GENERATED, FAILED, RUNNING, NO_STATUS

Sample response

Possible values: GENERATED, FAILED, RUNNING, NO_STATUS



Was this page helpful? Yes No Submitting... Thank you

Comments