How to Optimize API Calls Using the fields Parameter in Citrix DaaS
Overview
To enhance the performance of your API calls in Citrix DaaS (formerly Citrix Virtual Apps and Desktops service) site, especially when querying large or complex data sets, our API supports the use of a fields parameter. This allows you to specify only the attributes you are interested in, reducing the load on the server and speeding up the response time. By default, if no fields parameter is provided, the API will retrieve all default properties, potentially including those that may require intensive computation.
Follow the prerequisites and examples to get started.
You can make API requests using the PowerShell code, C# code, Python, or any tool that supports invoking the REST API.
Why Use fields?
- Faster Responses: Avoid fetching unnecessary or computationally expensive fields.
- Reduced Data Size: Only the specified fields are returned, minimizing the size of the response payload.
- Better Resource Usage: Optimize both server and client resources by limiting the scope of the query.
Prerequisites to use the fields Parameter
- Read Get started with Citrix Cloud APIs section to ensure that you have the
bearer token. - Get
siteidfrom How to get site id API. - Invoke the API described in this document from a client host.
Availability of the fields Parameter
The fields parameter is supported in most of our GET APIs, like GET /Machines . However, we recommend checking the specific API documentation for each endpoint to confirm whether fields is available. This ensures that you can optimize your queries by retrieving only the necessary fields for each API call.
Use the fields Parameter using any REST API tool
Learn from the following example to use fields in your Citrix DaaS site using any REST API tool.
Request Without fields
By default, the following API request will return all fields of the queried object(s):
GET https://api.cloud.com/cvad/manage/Machines HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4
Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1
<!--NeedCopy-->
Request With fields
To query only specific fields (e.g., Id, Uid, DnsName, and Name), include the fields parameter in the request:
GET https://api.cloud.com/cvad/manage/Machines?fields=Id,Uid,DnsName,Name HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
Authorization: CWSAuth bearer=<token-from-prerequisites>
Citrix-CustomerId: loy6oujtu6a4
Citrix-InstanceId: 22ded57c-0306-47e4-b6e8-fed6252759e1
<!--NeedCopy-->
Sample Response
Here’s an example of the difference in the response between querying all fields and using the fields parameter:
Without fields:
HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 1440
content-Type: application/json; charset=utf-8
date: "Mon, 07 Dec 2020 09:01:09 GMT"
Server: Citrix Systems, Inc.
{
"Items": [
{
"Id": "cf8582de-61dd-4c61-9649-636004c89907",
"Uid": 1,
"AgentVersion": null,
"AllocationType": "Random",
"ApplicationsInUse": [],
"AssociatedUsers": [],
"MachineCatalog": {
"Id": "b2a2acbc-bfe2-48cd-af62-c1c349789abb",
"Uid": 1,
"Name": "MC_01"
},
"ContainerScopes": [
{
"Scopes": [
{
...
}
],
"ScopeType": "MachineCatalog"
},
{
"Scopes": [
{
...
}
],
"ScopeType": "DeliveryGroup"
}
],
"ControllerDnsName": null,
"DeliveryGroup": {
"Id": "2544a873-39cb-4953-bb83-09afd3c6c0d7",
"Uid": 1,
"Name": "DG_01"
},
"DeliveryType": "DesktopsAndApps",
"Description": null,
"DesktopConditions": [],
"DnsName": "OrchVM-000001.DEVPORTAL.LOCAL",
"Hosting": {
...
},
...
"Name": "DEVPORTAL\\OrchVM-000001",
...
},
{
"Id": "8bd7c72f-1a4c-4e00-ae4f-bf2eb34457f9",
"Uid": 2,
"AgentVersion": null,
"AllocationType": "Random",
"ApplicationsInUse": [],
"AssociatedUsers": [],
"MachineCatalog": {
"Id": "b2a2acbc-bfe2-48cd-af62-c1c349789abb",
"Uid": 1,
"Name": "MC_01"
},
"ContainerScopes": [
{
"Scopes": [
{
...
}
],
"ScopeType": "MachineCatalog"
},
{
"Scopes": [
{
...
}
],
"ScopeType": "DeliveryGroup"
}
],
"ControllerDnsName": null,
"DeliveryGroup": {
"Id": "7b951c6b-b56a-473e-be8e-7745a1a83d8b",
"Uid": 2,
"Name": "DG_HR"
},
"DeliveryType": "DesktopsAndApps",
"Description": null,
"DesktopConditions": [],
"DnsName": "OrchVM-000002.DEVPORTAL.LOCAL",
"Hosting": {
"HostedMachineId": null,
"HostedMachineName": null,
"HostingServerName": null,
"LastHostingUpdateTime": "",
"HypervisorConnection": {
"Id": "",
"Uid": null,
"Name": null
},
"ImageOutOfDate": false
},
...
"Name": "DEVPORTAL\\OrchVM-000002",
...
}
]
}
<!--NeedCopy-->
With fields=Id,Uid,DnsName,Name:
HTTP/1.1 200 OK
citrix-transactionid: f10859e0-63a9-4c2a-a51e-a126416246dc
content-Length: 1440
content-Type: application/json; charset=utf-8
date: "Mon, 07 Dec 2020 09:01:09 GMT"
Server: Citrix Systems, Inc.
{
"Items": [
{
"Id": "cf8582de-61dd-4c61-9649-636004c89907",
"Uid": 1,
"DnsName": "OrchVM-000001.DEVPORTAL.LOCAL",
"Name": "DEVPORTAL\\OrchVM-000001"
},
{
"Id": "8bd7c72f-1a4c-4e00-ae4f-bf2eb34457f9",
"Uid": 2,
"DnsName": "OrchVM-000002.DEVPORTAL.LOCAL",
"Name": "DEVPORTAL\\OrchVM-000002"
}
]
}
<!--NeedCopy-->
Best Practices
-
Identify Required Fields: Before making your API call, identify the specific fields your application needs and list them in the
fieldsparameter. -
Test Response Times: Test API calls with and without the
fieldsparameter to observe the improvement in response time, especially when querying large data sets.
Ensure you verify the field names in the API documentation before making the request.