Typed Queries

Typed queries require you to construct a request URL that specifies an object type and optional parameters. Use this URL with a GET request to return query results.

Query Syntax

Typed queries have the following syntax:

API-URL/query?type=name[&param][&param ... ][&filter]

API-URL is a URL of the form https://vcloud.example.com/api.
name is the name of a query type. Type names are case-sensitive.
param is an optional query parameter. Zero or more parameters are allowed. See Query Parameters.
filter is an optional filter expression. At most one filter expression is allowed. See Filter Expressions.

Query Types

Each query type returns its result set as an XML document in which objects are represented as elements and object properties are represented as attributes, pairing the name of the property with its value at the time the request was made. By default, result sets are returned in the records format, which shows all database records for each object. Most queries also support the references format, which returns a set of object references, including name, type, and href attributes. All queries that support the records format also support the idrecords format. For more information about the format parameter, see Query Parameters.

Query Reference

The vCloud API schema reference includes reference material for all queries. The schema reference is available at https://code.vmware.com.

Listing All Queries

You can retrieve a summary list of all typed queries types accessible to the currently authenticated user by making a request like this one:

GET https://vcloud.example.com/api/query

The response is a QueryList element that contains a Link for every query. The href value of each Link is a URL you can GET to run the query specifying the default format.

<?xml version="1.0" encoding="UTF-8"?>
<QueryList
   type="application/vnd.vmware.vcloud.query.queryList+xml"
   href="https://vcloud.example.com/api/query"
   ... >
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.references+xml"
      name="organization"
      href="https://vcloud.example.com/api/query?type=organization&amp;format=references" />
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.records+xml"
      name="organization"
      href="https://vcloud.example.com/api/query?type=organization&amp;format=records" />
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.idrecords+xml"
      name="organization"
      href="https://vcloud.example.com/api/query?type=organization&amp;format=idrecords" />
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.references+xml"
      name="adminOrgNetwork"
      href="https://vcloud.example.com/api/query?type=adminOrgNetwork&amp;format=references" />
   ...
   </QueryList>

If you make a query whose result set you do not have rights to view, a response code of ACCESS_TO_RESOURCE_IS_FORBIDDEN (403) is returned.

Simple Typed Query

This simple typed query retrieves a list of all users in your organization and returns a response in the default (records) format.

GET https://vcloud.example.com/api/query?type=user

Response:

<QueryResultRecords
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   name="user"
   type="application/vnd.vmware.vcloud.query.records+xml"
   href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=records"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://vcloud.example.com/api/v1.5/schema/master.xsd">
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.references+xml"
      href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=references"/>
   <UserRecord
      deployedVMQuota="0"
      fullName="User One"
      identityProviderType="INTEGRATED"
      isEnabled="true"
      isLdapUser="false"
      name="bob"
      numberOfDeployedVMs="0"
      numberOfStoredVMs="0"
      storedVMQuota="0"
      href="https://vcloud.example.com/api/admin/user/39"
      storedVMQuotaRank="-1"
      deployedVMQuotaRank="-1"/>
   <UserRecord
      deployedVMQuota="0"
      fullName="User Two"
      identityProviderType="INTEGRATED"
      isEnabled="true"
      isLdapUser="false"
      name="zorro"
      numberOfDeployedVMs="0"
      numberOfStoredVMs="0"
      storedVMQuota="0"
      href="https://vcloud.example.com/api/admin/user/24"
      storedVMQuotaRank="-1"
      deployedVMQuotaRank="-1"/>
   <UserRecord
      deployedVMQuota="0"
      fullName="Example User"
      identityProviderType="INTEGRATED"
      isEnabled="true"
      isLdapUser="false"
      name="nobody"
      numberOfDeployedVMs="0"
      numberOfStoredVMs="0"
      storedVMQuota="0"
      href="https://vcloud.example.com/api/admin/user/58"
      storedVMQuotaRank="-1"
      deployedVMQuotaRank="-1"/>
</QueryResultRecords>

This simple typed query retrieves the same list of all users in your organization and returns a response in the references format.

GET https://vcloud.example.com/api/query?type=user&format=references

Response:

<UserReferences
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   name="user"
   type="application/vnd.vmware.vcloud.query.references+xml"
   href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=references"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... 
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=records" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="bob"
      href="https://vcloud.example.com/api/admin/user/39" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="zorro"
      href="https://vcloud.example.com/api/admin/user/24" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="nobody"
      href="https://vcloud.example.com/api/admin/user/58" />
</UserReferences>

Query With Parameters

This query retrieves a list of all users in your organization and returns a response in the records format. The query includes a sortAsc=name parameter, so the result set is sorted by object name.

GET https://vcloud.example.com/api/query?type=user&format=references&sortAsc=name

Response:

<UserReferences
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="3"
   pageSize="25"
   page="1"
   name="user"
   type="application/vnd.vmware.vcloud.query.references+xml"
   href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=references"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/query?type=user&amp;page=1&amp;pageSize=25&amp;format=records" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="bob"
      href="https://vcloud.example.com/api/admin/user/39" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="nobody"
      href="https://vcloud.example.com/api/admin/user/58" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="zorro"
      href="https://vcloud.example.com/api/admin/user/24" />
</UserReferences>

This query retrieves a list of all users in your organization and returns a response in the records format. The query includes a filter=ldapUser==true parameter, so the result set lists the subset of users who are imported from LDAP. Note that you can filter on a record (attribute) value even though you specify the references format.

GET https://vcloud.example.com/api/query?type=adminUser&format=references&filter=ldapUser==true

Response:

<?xml version="1.0" encoding="UTF-8"?>
<UserReferences
   xmlns="http://www.vmware.com/vcloud/v1.5"
   total="2"
   pageSize="25"
   page="1"
   name="user"
   type="application/vnd.vmware.vcloud.query.references+xml"
   href="https://vcloud.example.com/api/query?type=adminUser&amp;page=1&amp;pageSize=25&amp;format=references&amp;filter=ldapUser==true"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ... >
   <Link
      rel="alternate"
      type="application/vnd.vmware.vcloud.query.records+xml"
      href="https://vcloud.example.com/api/querytype=adminUser&amp;page=1&amp;pageSize=25&amp;format=records&amp;filter=ldapUser==true" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="bob"
      href="https://vcloud.example.com/api/admin/user/39" />
   <UserReference
      type="application/vnd.vmware.admin.user+xml"
      name="zorro"
      href="https://vcloud.example.com/api/admin/user/58" />
</UserReferences>