API change history

8.18.0 API fixes and improvements

/admin/exports endpoint disabled: The /admin/exports endpoint is now disabled. Any attempt to use this endpoint returns a 403 Forbidden error.

For IBM support cases, you can use the API or user interface to export diagnostics data to IBM ECuRep or IBM Blue Diamond.
- In the API, use the /admin/exportstoibm endpoint.
- In the user interface, navigate to Settings > Maintenance, click the Telemetry & diagnostics tab, and scroll to the Diagnostics section.
Audit log export enhancement: In the Turbonomic API, you can now filter audit logs by date using the new optional days query parameter in the existing audit log export endpoint. This parameter lets you retrieve logs from the specified number of days before the current date.
EOL for deprecated API fields: Deprecated APIs that were scheduled to be removed in version 8.15.1 are now rescheduled to be permanently removed in version 8.20.1.

8.17.0 API fixes and improvements

Assign and remove user-defined tags on entities and groups
- Use the POST /entities/entity_Uuid/tags endpoint to assign tags to a specific entity. The existing tags for the entity are not overwritten when invoking the API.
- Use the POST /groups/entity_Uuid/tags endpoint to assign tags to a specific group. The existing tags for the group are not overwritten when invoking the API.
- Use the DELETE /entities/entity_Uuid/tags?key=ExampleTagKey endpoint to delete tags of a specified entity. The tags defined in your list are deleted. If no list is provided, then all tags for the entity are deleted.
- Use the DELETE /groups/entity_Uuid/tags?key=ExampleTagKey endpoint to delete tags of a specified group. The tags defined in your list are deleted. If no list is provided, then all tags for the group are deleted.
New support for rejecting actions through the Actions API: POST /actions/{action_uuid} endpoint request now supports rejecting actions. Only actions in a READY state can be rejected. The rejected actions will not be recommended by Turbonomic for the next 7 days.
The PARKER_AUTOMATOR role is now available: The PARKER_AUTOMATOR role is now supported for POST, GET, and PUT requests to the following user management endpoints:
- /authorization/oauth2/clients
- /users
- /users/ldap
Users with the PARKER_AUTOMATOR role can park workloads manually or automatically (by attaching parking schedules to workloads), and view all charts and data. However, these users cannot perform the following tasks:
- Manage parking schedules (add, create, or delete schedules)
- Place workloads
- Create policies and templates
- Run plans
- Execute actions
Pause parking schedule now supports groups: The /parking/enforcementPauses endpoint now supports group IDs for both POST and DELETE requests. You can include either the entityUuids or groupUuids field in the request, and the response will return the corresponding identifier.
Audit log endpoint is now available: Use the GET /admin/auditlogs endpoint to view audit log data such as login, logout, account management, policy changes, and authorization-related events for Turbonomic.

8.16.0 API fixes and improvements

The respectActionModeSetting parameter is now available: For the Scenarios endpoint, the POST /scenarios request for a plan scenario now supports the respectActionModeSetting parameter with a default value of false. If you set the value to true, the plan configuration applies the action mode settings in the automation policy for the entities in the plan's scope.
API changes for automation and default policy selection are now implemented: A new API field, {_}removeAutomationPolicyList{_}, has been added to the _configChanges_ section in the /scenarios API. Passing the policy UUID with the _disabled_ field set to true will allow the plan to ignore the specified policy when the Import Action Mode setting is enabled, provided the backend feature flag is also enabled.
Manual parking actions for workload set are now supported: *POST /parking/bulkActionRequest* API now supports group Ids. The Uuids/groupUuid fields added has been added to the endpoint request and the response has a new group. A new Request now requires either entityUuids or groupUuids, wherein the response will provide either entityUuid or groupUuid.
The parking policies endpoint is now available: The parking policies endpoint (/parking/policies) supports the following API requests:
- Create a parking policy (POST /parking/policies).
- Get the details of a parking policy (GET /parking/policies/{policy_Uuid}).
- Update a parking policy (PUT /parking/policies/{policy_Uuid}).
- Delete a parking policy (DELETE /parking/policies/{policy_Uuid}).
- Get a list of parking policies (GET /parking/policies).
API responses no longer return the JBoss target: The JBoss target is no longer supported. Starting with version 8.15.4, when you make an API request in the /targets and /probes endpoints, the response no longer returns the JBoss target.

8.15.0 API fixes and improvements

Vendor link in the API response for vCenter based hosts: For vCenter based hosts, when you execute GET /entities/{entityUuid} in the API, the response now shows a vendor link to the appropriate section in vCenter. This link corresponds to the Vendor link field in the Entity information chart in the UI.

8.14.0 API fixes and improvements

Security improvement: Hide exception details in API responses: API error responses must not include exception and class information, as this could reveal internal implementation details to an attacker.

Turbonomic now disables the output details for security exceptions by default. The API caller can still understand the nature of an error by inspecting the type and message fields.
Removal of API parameters for the /action/availablemodes API call: API Parameters *entity_type and *action_type are removed from the /action/availablemodes API call.

8.13.0 API fixes and improvements

Added regex validation for /search API calls: For API developers, regex validation is added for /search API calls. If you specify a * as the first character of the search when you search for a group in the UI, you no longer receive a 500 error that indicates an internal system error. Instead, you receive a 400 error that correctly indicates invalid user input.

8.12.0 and earlier API fixes and improvements

The GroupType parameter now accepts ResourceGroup as a valid enum: For API developers, the GroupType parameter in the API now accepts ResourceGroup as a valid enum for entities that belong to resource groups, such as VMs. For backward compatibility, the API continues to accept the existing Resource enum. However, API responses include only ResourceGroup.

The Parking APIs are now available: Turbonomic supports parking actions for cloud resources. These actions stop your cloud resources for a period to help you reduce your cloud expenses, and then start these resources later when you need them. Use the Parking endpoint to get a list of parkable entities and execute parking actions on demand.

You can also enforce parking actions according to a schedule. In the Schedules endpoint, use /schedules/timespans/ requests to configure parking schedules and attach the schedules to parkable entities. When parking schedules are attached to entities, use the Parking endpoint to pause and resume schedules as needed.
The API now allows an operator field in the instanceType and newInstanceType action filters: The API now allows an operator field in the instanceType and newInstanceType action filters. The operator can be EQ (equals) or NEQ (not equal to). If no value is set, the action filter uses EQ.
The API no longer includes historical price index data in various API methods that return entity statistics: The API no longer includes historical price index data in various API methods that return entity statistics. Price index is still available for the most recent real-time projected data, and in responses for plan-related requests.

This specifically refers to the StatSnapshotApiDTO structure when epoch is set to CURRENT or HISTORICAL.

API users can now search for entities by their tag as follows: GET /tags/entities?key=<tagKey>: API users can now search for entities by their tag by calling GET /tags/entities?key=<tagKey>, which includes entities with a slash (/) within a tag string.

Note:
The existing API call GET /tags/<tagKey>/entites will be permanently deleted in a future release. Until its removal, you can use both of these methods.
API users can now filter and sort targets: API users can now filter and sort the list of targets to restrict their view to only their relevant targets.
The following parameters were added to the list of targets request:
- target type (AWS, AWS_BILLING, ACTIONSCRIPT, ACTIONSTREAM_KAFKA, APPDYNAMICS, APPINSIGHTS, AZURE_BILLING, AZURE_EA, AZURE_SERVICE_PRINCIPAL, CISCO_HYPERFLEX, CISCO_UCS_MANAGER, DATADOG, DYNATRACE, EMC_SCALEIO, EMC_VMAX, FLEXERA, GCP_BILLING, GCP_SERVICE_ACCOUNT, HP_ONEVIEW, HPE_3PAR, HYPER_V, INSTANA, JVM, KUBERNETES, MYSQL, NETAPP, NEWRELIC, NUTANIX, ORACLE, PURE, SNMP, SQLSERVER, SERVICENOW, TOMCAT, VMM, VMWARE_HORIZON, WMI, WEBLOGIC, WEBSPHERE, VCENTER)
- validation status (FAILED, IN_PROGRESS, SUCCESS)
- health state (CRITICAL, MAJOR, MINOR, NORMAL)
The following parameters for sorting the list of targets were added: target type and health state.
Kubeturbo is using a deprecated API for the APIRequestCount query: Kubeturbo is using a deprecated API for the APIRequestCount query. This issue is now fixed.

For API developers, when executing requests on the Search endpoint, the API does not paginate the returned result: This issue is now fixed.

The API now supports reservations with cluster affinity: When creating reservations, you can now specify affinity rules for the reserved VMs. You can ensure all the VMs in a reservation deploy to the same cluster. If you do not specify affinity, the VMs deploy to any clusters in the scope. This is the same as earlier behavior for reservations.

For more information, see Affinity Rules.
The /supplychains/leafEntities endpoint is now available: This release introduces the /supplychains/leafEntities endpoint that you can use to define your own supply chain topology. This endpoint returns a list of 'leaf entities' related to a 'seed entity'.

For more information, see Getting Leaf Entities from a Supply Chain Root.
The maximum entries returned for GET and POST methods is 500: GET and POST methods return a maximum of 500 entries when run on ServiceEntities, Groups, or BusinessAccount endpoints. You should always check for pagination in your results.

The API now includes the Plan Destinations endpoint: A plan destination is an external resource where plan results can be uploaded. Currently, you can upload the results of a Migrate to Cloud plan to the Azure Migrate portal. Use the Plan Destinations endpoint to get plan destinations and run uploads.
When deleting a reservation, you can now specify whether to permanently delete that reservation: The API now includes the new reservation_force_delete parameter that you can pass along with a DELETE call to a specific reservation. When reservation_force_delete = true, the system removes the reservation permanently, no matter what state it is in. Before this release, a reservation that you deleted via the API or user interface continued to display for deletion, and was only permanently deleted after 48 hours.
The API includes a new LABEL commodity type: The commodityType enum includes a new LABEL commodity type.
For API developers, when a reservation you create fails, the returned DTO includes more data about the failure: When you create a reservation, and the reservation fails, the API returns a DTO to explain the cause of the failure. This DTO includes new fields:
- timespan: Indicates whether the reservation calculation was based on realtime or historical resource utilization data. Can be one of:
  - Current: The calculations were based on realtime utilization data
  - Historical: The calculations were based on historical utilization
- cluster: The name of the cluster that came the closest to being able to provide the resources that the reservation needed.
- hrefCluster: A link to stats for the closest-seller cluster.
- hrefEntity: A link to stats for the closest-seller entity that is a member of the closest-seller cluster.
For example, the DTO can include data similar to the following for a placement failure:
```
"placements": {
    "failureInfos": [
        {
            "resource": "StorageAmount",
            "timespan": "Historical",
            "closestSeller": {
                "uuid": "74167780552264",
                "displayName": "QSGRID01:DC6DS2",
                "className": "Storage",
                "cluster": "StorageCluster-A",
                "hrefEntity": "/reservations/stats/74167780552264",
                "hrefCluster": "/reservations/stats/74167780552265"
            },
            "maxQuantityAvailable": 248294.59024047852,
            "quantityRequested": 273184.5625,
            "units": "MB"
        }
    ]
}
 
```
Handling of non-executable actions has been improved: This release improves the handling of actions that are currently not executable due to prerequisite actions.

For example, in order to suspend Host A, VM_01 in the host must first move to Host B. However, Host B only has capacity for one VM and is currently hosting VM_02. In this case, Host A suspension is blocked by two prerequisite actions – VM_02 moving to another host and VM_01 moving to Host B.

The Action Details page for the main action (Host A suspension in the example) now shows the following information:

"Blocked by actions on target or destination that need to be executed first."

For earlier releases, the Action Details page indicated that the action is blocked by a policy.

For API developers, the ActionApiDTO now shows this state. Turbonomic sets the BLOCKED_BY key of the relatedActionsCountByType parameter to 0, which indicates that an action is currently not executable due to prerequisite actions.

When all the prerequisite actions have been executed, the main action becomes executable.
When you examine a failed reservation via the API, the data now returns a reason for the failure: After you create a reservation, you can GET the reservations endpoint for data about the current reservations in your environment. The resulting data includes a status. If the status is PLACEMENT_FAILED, Turbonomic could not place all the workloads in the reservation for some reason. The placements field in the data includes invalidInfo to give a reason for the placement failure. The reason can be:
- MARKET_CONNECTIVITY_ERROR: The reservation process could not connect to the Market component for some reason.
- MARKET_NOT_READY: The market does not have data from the Headroom plans for the given reservation scope.
- INVALID_CONSTRAINTS: The reservation policies include conflicting or invalid constraints.
For example, the data for a single reservation might include the following data:
```
"demandEntities": [
    {
        "template": {
            "uuid": "215167980658768",
            "displayName": "MyVmTemplate",
            "className": "VirtualMachineProfile"
        },
        "placements": {
            "invalidInfo": {
                "invalidReason": "MARKET_CONNECTIVITY_ERROR"
            }
        }
    }
]
```