Version 2020

Improve Performance by Working with Partial Resources

While API endpoints define full response models, you may only need a subset of the available data. You can ask the server to only send the fields you need and get a partial response instead. This helps improve performance, since extra resources are not devoted transferring, parsing, and storing unnecessary fields.

MicroStrategy supports top-level field selection on most endpoints.

  • For endpoints that return a JSON object, the client specifies which fields to include for the root object.
  • For endpoints that return a JSON array, the client specifies which fields to include for every element of the root array.

Field selection only allows the API caller to specify fields at the root level or root level within a collection. It is not possible to specify field selection for child or nested objects.

Supported Endpoints

Top-level field selection is supported for most endpoints that return JSON responses. You can check if an endpoint supports the standard fields parameters through the REST API Explorer.

Some exceptions are:

  • The following Data API v2 endpoints that return grid data do not support field selection. Instead, they provide other means of managing response size, such as pagination.

    POST /v2/reports/{reportId}/instances

    GET /v2/reports/{reportId}/instances/{instanceId}

    POST /v2/cubes/{cubeId}/instances

    GET /v2/cubes/{cubeid}/instances/{instanceId}

    GET /v2/dossiers/{dossierId}/instances/{instanceId}/chapters/{chapterKey}/visualizations/{visualizationKey}

  • This following endpoint comes with a fields parameter specifically designed for its use cases. This is different from the general field selection described in this topic.

    GET /dataset/{datasetId}:

Specify Fields

The fields query parameter is exposed on endpoints that support field selection.

  • Specify a comma-separated list of field names, without any white space.

    fields=id,name

  • When the fields parameter is omitted in a query string or had an empty value, the full response is returned.
  • Field selection only applies to successful responses. Error responses are always returned in full.

Field Selection on a Root Object

For endpoints that return a JSON object, the client specifies which fields to include for the root object. If a field is included that holds an array/object value, the entire nested array/object value is kept.

Here is an example using GET /projects/MicroStrategy%20Tutorial?fields=id,name,owner.

{
    "id": "B19DEDCC11D4E0EFC000EB9495D0F44F",
    "name": "MicroStrategy Tutorial",
    "owner": {
        "name": "Administrator",
        "id": "54F3D26011D2896560009A8E67019608"
    }
}

Here is an example of full representation without fields.

{
    "acg": 255,
    "id": "B19DEDCC11D4E0EFC000EB9495D0F44F",
    "name": "MicroStrategy Tutorial",
    "status": 0,
    "alias": "",
    "description": "MicroStrategy Tutorial project and application set designed to illustrate the platform's rich functionality. The theme is an Electronics, Books, Movies and Music store. Employees, Inventory, Finance, Product Sales and Suppliers are analyzed.",
    "dateCreated": "2001-01-02T20:42:04.000+0000",
    "dateModified": "2019-06-28T03:32:24.000+0000",
    "owner": {
        "name": "Administrator",
        "id": "54F3D26011D2896560009A8E67019608"
    }
}

Field Selection on Root Array Elements

For endpoints that return a JSON array, the client specifies which fields to include for every element of the root array. If a field is included and it holds an array/object value, the while nested array/object value is kept.

Here is an example using GET /projects?fields=id,name.

[
    {
        "id": "AF09B3E3458F78B4FBE4DEB68528BF7B",
        "name": "Human Resources Analysis Module"
    },
    {
        "id": "B19DEDCC11D4E0EFC000EB9495D0F44F",
        "name": "MicroStrategy Tutorial"
    }
]