Using query parameters to change the shape of a response

Article
09/29/2021

The OneDrive API provides several optional query parameters that can be used to control the specific data returned in a response.

Covered in this topic:

Selecting properties
Expanding collections
Sorting collections

Selecting properties

You can use the select query string parameter to provide a comma-separated list of properties to return on Items.

Example

This example selects only the name and size properties to be returned, when retrieving the children of an item.

GET /drive/root/children?select=name,size

By submitting the request with the select=name,size query string, the objects in the response will only have those property values included. When using the select statement, you need to specify all properties to return in the statement.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "13140a9sd9aba",
      "name": "Documents",
      "size": 1024
    },
    {
      "id": "123901909124a",
      "name": "Pictures",
      "size": 1012010210
    }
  ]
}

Expanding collections

In OneDrive API requests, children collections of referenced items are not automatically expanded. This is by design because it reduces network traffic and the time it takes to generate a response from the service. However, in some cases you might want to include those results in a response.

You can use the expand query string parameter to instruct the OneDrive API to expand a children collection and include those results.

For example, to retrieve the root drive information and the top level items in a drive you use the expand parameter as in the example below. This example also uses a select statement to only return the id and name properties of the children items.

GET /drive/root?expand=children(select=id,name)

The request returns the collection items, with the children collection expanded.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "12312312541",
  "name": "root",
  "size": 218753122201,
  "webUrl": "https://onedrive.live.com/?cid=0f040...",
  "folder": {
    "childCount": 4
  },
  "children": [
    {
      "id": "F04AA961744A809!48443",
      "name": "Applications",
    },
    {
      "id": "F04AA961744A809!92647",
      "name": "Attachments",
    },
    {
      "id": "F04AA961744A809!93269",
      "name": "Balsmiq Sketches",
    },
    {
      "id": "F04AA961744A809!65191",
      "name": "Camera imports",
    }
  ]
}

Sorting collections

You can use the orderby query string to control the sort order of the items returned from the OneDrive API. For a collection of items, use the following fields in the orderby parameter.

name
size
lastModifiedDateTime

Note that in OneDrive for Business and SharePoint Server 2016, the orderby query string only works with name and url.

To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space, for example, ?orderby=name%20desc.

For example, to return the contents of the root of a drive in OneDrive, ordered largest to smallest, use this syntax: /drive/items/root/children?orderby=size%20desc.

Optional OData query parameters

Here is a table of optional OData query parameters you can use in your OneDrive API requests.

Name	Value	Status	Description
expand	string	available	Comma-separated list of relationships to expand and include in the response. For example, to retrieve the children of a folder use `expand=children`.
select	string	available	Comma-separated list of properties to include in the response.
skipToken	string	available	Paging token that is used to get the next set of results.
top	int	available	The number of items to return in a result set. The OneDrive API may have a hard limit that prevents you from asking for more items per response.
orderby	string	available	Comma-separated list of properties that are used to sort the order of items in the response collection. Works for `name`, `size`, and `lastModifiedDateTime` fields.
filter	string	not available	Filter string that lets you filter the response based on a set of criteria.

Note: The OData standard prefixes these terms with a $. OneDrive API supports using these query parameters either with or without the special character, but you must be consistent throughout the request with your usage of the $ character on these arguments.

Share via