This REST API reference is for those interested in developing automation workflows and other applications using Tintri VMstore. This document explains how developers can leverage REST APIs over HTTP.
Tintri requires that all requests are done over SSL. All requests to port 80 are converted to port 443 for VMstore.
All strings passed to and from the Tintri APIs need to be UTF-8 encoded.
Over time, the Tintri APIs will change. Future versions may add new managed entities or keys. To keep older clients working, the behavior and return values with given parameters will not change from the documented behavior except for undocumented request parameters or additional response keys.
With this in mind, clients should avoid passing undocumented parameters and accept keys that are not currently documented. API clients will have to be modified to obtain new Tintri features.
API Version | TXOS Version | TGC Version |
---|---|---|
v310.1 | 3.1.0.x | --- |
v310.11 | 3.1.1.x | --- |
v310.21 | 3.2.1.x | 2.0.0.1 |
v310.31 | 4.0.0.x | 2.1.0.x |
v310.41 | 4.1.0.x | 2.1.0.x |
v310.51 | 4.2.0.x | 3.0.0.x |
v310.53 | 4.2.1.x | 3.0.1.x |
v310.61 | 4.3.0.x | 3.5.0.x |
v310.64 | 4.3.2.x | 3.5.0.x |
v310.66 | 4.3.3.x | 3.5.1.x |
v310.71 | 4.4.0 | 3.7.0 |
v310.81 | 4.4.1 | 3.8.0 |
v310.91 | 4.5.0 | 4.0.0 |
v310.93 | 4.5.1 | 4.1.x |
v310.101 | 4.6.0.x | 5.0.0 |
v310.111 | 5.0.0.x | 5.0.1 |
v310.121 | 5.1.0.x | 5.2.x |
v310.131 | 5.2.0.x | 5.3.x |
v310.141 | 5.3.0.x | 5.3.x |
v310.151 | 5.4.x | 5.4.x |
v310.161 | NA | 5.5.0.x |
v310.171 | 5.4.2.x | 5.5.2.x |
Tintri uses the standard HTTP error code syntax. The error codes are listed below:
HTTP Status Code | Tintri explanation |
---|---|
200 | Successful API call with non empty result body. |
204 | Successful API call with empty result body. |
400 | Bad request - Request validation failed. Request content incorrect/invalid. |
401 | Non authorized API access - User needs to successfully login with needed privileges to perform the operation. |
403 | Forbidden - invalid credentials or licenses. Some APIs, like /v310/vm/sync require a license. |
404 | API not found. |
405 | Method not allowed. |
409 | Conflict - object already exists when creating object. |
500 | Internal Error - something went wrong in the server side processing. |
501 | Not Implemented - For example if supported by VMstore but not TGC. |
503 | Service unavailable - External service, like active directory, is unavailable. This is usually temporary and worth retrying later. |
When an API error occurs, TintriError is returned. An example is below:
New users can be created. Each user when created is assigned a role. Currently, the roles are:
Role | Read | Write | User Management |
---|---|---|---|
Admin | Yes | Yes | Yes |
System Admin | Yes | Yes | No |
Read Only | Yes | No | No |
The Read Only role is only allowed to read resources from the Tintri Appliance. This means that all GET APIs are allowed.
The System Admin role is the Read Only role plus updating and creating resources except for user management. This means that all GET, PUT, POST DELETE APIs are allowed except the user management DELETE, POST and PUT APIs.
The Admin role is the System Admin role plus updating and creating user management. This means that all GET, POST, PUT, and DELETE APIs are allowed.
The admin user is a special user that cannot be deleted or modified.
Filtering parameters are based on RFC 6570.
Format | ?parm1=value&param2=value2&param3=value3? |
---|---|
Example | ?type=SCHEDULE_SNAPSHOT&consistency=CRASH_CONSISTENT&vmId=5CFC98F0-731C-2474-FE84-0BC2C3A28543-VIM-0000000000000020 |
Many of the Tintri APIs with GET methods return large numbers of objects. For the convenience of the client, a paged response is provided. The paged response is in the form of a Page object which is composed as follows:
Name | Description |
---|---|
absoluteTotal | The absolute number of objects within the managed entity. This number includes active and deleted objects with no filtering. |
completedIn | Time in milliseconds indicating how long it took to serve the request. |
filteredTotal | The number of objects returned as specified by the filter. If no filter was requested, then the value is the same as total. |
items | The API specific items. For each API, items will contain different information. |
lastUpdatedTime | The time when the page was last updated. |
limit | The client requested limit for the number of items in a page. Default is 2000. |
next | The URL query string to fetch the next page. |
offset | The client requested index of an object in the table. Possible formats include numeric offset, UUID offset, and a substring name. |
offsetMatchFound | Indicates if the requested object/(s) is/are found. |
overflow | A flag giving notice the amount of data did not fit into the given specified or default offset. |
page | The current page number |
pageTotal | The total number of objects in the page. |
prev | The URL query string to fetch the previous page. |
total | The number of active objects in the managed entity. |
Session login uses the session resource. An HTTP POST with the user name, password, and role is sent. A session cookie is returned and this cookie is used in all subsequent API invocations.
https://ttvm38.tintri.com/api/v310/session/login
{"username":"admin", "typeId":"com.tintri.api.rest.vcommon.dto.rbac.RestApiCredentials", "password":"mypass"}
HTTP status 200. User role name
Session logout uses the session resource. An HTTP GET is used with the session cookie provided in the session login.
https://ttvm38.tintri.com/api/v310/session/logout
HTTP status 204
Request allows for multiple properties of multiple objects to be updated at one time. The example below shows the JSON for updating the acceptIncomingTraffic property in DatastoreReplicationPath.
https://ttvm38.tintri.com/api/v310/datastore/default/replicationInfo
{'typeId': 'com.tintri.api.rest.v310.dto.Request', 'objectsWithNewValues': [{'typeId': 'com.tintri.api.rest.v310.dto.domain.beans.repl.DatastoreReplicationPath' 'acceptIncomingTraffic': 'False' }], 'propertiesToBeUpdated': ['acceptIncomingTraffic'] }
HTTP status 204.
MultipleSelectionRequest allows for multiple properties on one object for multiple resources at one time. The example below shows the JSON for updating the minNormalizedIops and minNormalizedIopsproperties in VirtualMachineQoSConfig for the API update QOS config.
https://ttvm38.tintri.com/api/v310/vm/qosConfig
{'typeId': 'com.tintri.api.rest.v310.dto.MultipleSelectionRequest', 'ids': ['A1D88A8A-8904-1E35-9DC2-589C317D31A6-VIM-00000000000001A5', 'A1D88A8A-8904-1E35-9DC2-589C317D31A6-VIM-0000000000000070' ] 'newValue': {'minNormalizedIops': '100', 'maxNormalizedIops': '248', 'typeId': 'com.tintri.api.rest.v310.dto.domain.beans.vm.VirtualMachineQoSConfig' } 'propertyNames': ['minNormalizedIops', 'maxNormalizedIops'] }
HTTP status 204.
GET | /v310/datastore/{uuid}/systemProperty | Returns a list of system properties and related information | VMstore Only |
GET | /v310/datastore/{uuid}/systemProperty/{propertyName} | Returns information on the specified system property | VMstore Only |
PUT | /v310/datastore/{uuid}/systemProperty | Updates a system property's custom value | VMstore Only |
DELETE | /v310/datastore/{uuid}/systemProperty{propertyName} | Removes the specified system property's custom value | VMstore Only |
POST | /v310/alert/notificationPolicy | Creates a new notification policy | All |
PUT | /v310/alert/notificationPolicy/{uuid} | Update an existing notification policy | All |
DELETE | /v310/alert/notificationPolicy/{uuid} | Delete an existing notification policy | All |
GET | /v310/alert/notificationPolicy/{uuid} | Get the notification policy associated with an ID | All |
GET | /v310/alert/notificationPolicy | Get all notification policies | All |
DELETE | v310/datastore/{uuid}/deleteAllCloudReplication | Deletes all per VM configurations that point to a cloud replication Link. | All | |
DELETE | /v310/datastore/{uuid}/deleteAllReplication | Deletes all per VM configurations that point to an asynchronous replication link. | All | |
PUT | /v310/datastore/{uuid}/fileShare/{fsName}/resetFileAcls | Resets the permissions of all the files on the specified share | VMstoreOnly | |
POST | /v310/datastore/{uuid}/pauseAsyncSyncReplication | Pause asynchronous and synchronous replication | All | |
POST | /v310/datastore/{uuid}/pauseCloudReplication | Pause cloud replication | All | |
GET | /v310/license/eval | Returns a list of all the evaluation licenses. | All | |
POST | /v310/license/eval/{feature} | Activates an evaluation license for a feature. | All | |
GET | /v310/servicegroup/{id}/quota/statsHistoric | Get all of the historic quota statistics slices for the service group. | All | |
GET | /v310/servicegroup/{id}/quotaPolicy | Returns the quota policy associated with the given service group. | All | |
POST | /v310/servicegroup/{id}/quotaPolicy | Create a quota policy for the given service group. | All | |
PUT | /v310/servicegroup/{id}/quotaPolicy | Update the quota policy for the given service group. | All | |
DELETE | /v310/servicegroup/{id}/quotaPolicy | Delete the quota policy associated with the given service group. | All | |
POST | /v310/servicegroup/{uuid}/statsDownloadable | Returns a URL for retrieving the service group historical performance statistics report. | TgcOnly | |
POST | /v310/session/{tintriSessionId}/invalidate | Invalidate a session by a user belonging to "Admin" role. | All | |
POST | /v310/snapshot/restore | Restore a snapshot from cloud as specified by the snapshot restore specification. | All |
GET | /v310/appliance/{uuid}/stagingAreaInfo | Gets the Tintri appliance staging area information, which includes details about the space, software uploaded | TgcOnly |
GET | /v310/appliance/{uuid}/stagingAreaInfo/availableSoftwares | Gets the Tintri appliance staging area available software information, which includes details of the software uploaded | TgcOnly |
POST | /v310/appliance/{uuid}/stagingAreaInfo/availableSoftwares/cancelupgrade | Cancel the VMstore software upgrade. | TgcOnly |
DELETE | /v310/appliance/{uuid}/stagingAreaInfo/availableSoftwares/{softwareuuid} | Delete the specified TxOS software from the staging area. | TgcOnly |
POST | /v310/appliance/{uuid}/stagingAreaInfo/availableSoftwares/{softwareuuid}/startupgrade | Upgrades the TXOS software to the specified VMstores. | TgcOnly |
GET | /v310/appliance/{uuid}/fileDirInfo/{path} | Fetch the file system information associated with the entity specified by path. | VMstoreOnly |
PUT | /v310/vm/relocate | Relocate a group virtual machines to another datastore. | TgcOnly |
PUT | /v310/vm/testRelocateVms | Validate the relocate VMs request for whether the provided VMs can be migrated to the specified destination datastore. | TgcOnly |
POST | /v310/appliance/{uuid}/rebootSecondary | Reboot the secondary controller. | VMstoreOnly |
GET | /v310/datastore/{uuid}/tag | Returns hypervisor tags in paginated form as specified by filter parameters in request. | All |
GET | /v310/datastore/{uuid}/tag/{tagId} | Returns hypervisor tag information for given {tagId}. | All |
POST | /v310/appliance/{uuid}/rpcReport | Generates a report of external RPC connections to filesystem in /var/log/tintri/rpc-connections-external.txt | VMstoreOnly |
GET | /v310/alert/notificationPolicy/allowedUserAlertIds | Returns a sorted list of user alert IDs that are allowed for Alert Notification Policy. The sort order is ascending. | All |
POST | /v310/appliance/{uuid}/expand/async | Expands the storage capacity of the Tintri appliance in asynchronous way. Progress can be monitored using /v310/task/{task-id} api. | VMstoreOnly |
POST | /v310/appliance/{uuid}/restartDb | Restarts the application database. | VMstoreOnly |
GET | /v310/datastore/{uuid}/hypervisorManagerConfig/{managerId} | Gets hypervisor manager configuration for given manager id and optionally refreshes the manager. If refresh is requested, API call is blocked until refresh completes. | VMstoreOnly |
GET | /v310/datastore/{uuid}/k8s/pod | Returns k8s pods. | All |
GET | /v310/datastore/{uuid}/k8s/container | Returns k8s containers. | All |
GET | /v310/datastore/{uuid}/k8s/pv | Returns k8s Persistent Volumes. | All |
GET | /v310/datastore/{uuid}/k8s/pvc | Returns k8s Persistent Volume Claims. | All |
GET | /v310/datastore/{uuid}/k8s/namespace | Returns k8s Namespaces. | All |
GET | /v310/datastore/{uuid}/k8s/deployment | Returns k8s Deployments. | All |
The API resources are presented below. The Data Overview button presents the Data Transfer Objects (DTOs) that are transferred between the Tintri server and the client. The API Overview and API Index buttons present different views of the API endpoints. To use the endpoints in a browser or a tool like Postman, the Tintri server and /api need to prefix the endpoints presented below; for example: http://vmstore.tintri.com/api/v310/vm