Selecting Folders, Files And Metadata In Sharepoint Rest Calls
The Problem of Querying SharePoint
A common challenge when working with SharePoint sites is the need to retrieve specific folders, files, and metadata from various document libraries and lists. While the SharePoint user interface allows simple browsing and searches, developers often require more precise and customizable queries.
The SharePoint REST API provides the capability to construct targeted requests to filter, select, expand, and order SharePoint entities. By using the various query parameters available, SharePoint objects like folders, documents, and list items can be retrieved efficiently through REST API calls.
Constructing REST Queries for SharePoint
The SharePoint REST API exposes endpoints that correspond to entities like sites, lists, libraries, folders, files, list items, users, and more. These endpoints support OData query options for filtering, selecting, ordering, and expanding the SharePoint objects.
Some common SharePoint REST API endpoints include:
- /_api/web/lists/getbytitle(‘Documents’) – For a SharePoint list like Documents library
- /_api/web/GetFolderByServerRelativeUrl(‘/Sites/My Site/Documents’) – For a folder in Documents library
- /_api/web/lists/getbytitle(‘Custom List’)/items – For items in a Custom List
To target specific folders, files, and metadata within these endpoints, parameters like $select and $filter can be appended to the endpoint URI. For example:
/_api/web/lists/getbytitle('Documents')?$select=Name,CreatedBy&$filter=Created gt 2019-01-01
This request filters for documents created after Jan 1, 2019 and returns only the Name and CreatedBy fields per document.
Filtering for Folders and Libraries
To retrieve contents within a specific SharePoint document library or folder, the $filter parameter can be used to restrict the results by path.
For example, the below request filters on the ServerRelativeUrl property to only return the contents of the Documents library:
/_api/web/lists/getbytitle('Documents')/items?$filter=FileSystemObjectType eq 0
We can further filter on ServerRelativeUrl to get a specific folder under Documents library:
/_api/web/lists/getbytitle('Documents')/items?$filter=FileSystemObjectType eq 0 and ServerRelativeUrl eq '/Sites/My Site/Documents/Reports'
This will return all items within the Reports folder in that library.
Retrieving Files by Name or Metadata
When querying the Files endpoint at /_api/web/GetFolderByServerRelativeUrl(‘<
Filtering on file name uses the Name metadata property:
/_api/web/GetFolderByServerRelativeUrl('/Sites/My Site/Documents')/Files?$filter=Name eq 'Report.xlsx'
Other metadata properties like Author or Created can also be used to filter results:
/_api/web/GetFolderByServerRelativeUrl('/Sites/My Site/Documents')/Files?$filter=AuthorId eq 45
/_api/web/GetFolderByServerRelativeUrl('/Sites/My Site/Documents')/Files?$filter=Created gt 2019-01-01
For custom metadata, the property name follows the format Property_[InternalName]. For example, to find files tagged as “confidential”:
/_api/web/GetFolderByServerRelativeUrl('/Sites/My Site/Documents')/Files?$filter=Property_Custom_Confidential eq 'Yes'
Expanding SharePoint Objects in Responses
By default, SharePoint objects returned in responses contain minimal attributes focusing on identifying properties like Id, Filename, Title etc. To show additional metadata fields, the $expand parameter is required.
For example, to return files with metadata like size, author, last modified date, we can specify:
/_api/web/GetFolderByServerRelativeUrl('/Sites/My Site/Documents')/Files?$expand=Author,Length,TimeLastModified
Expanding Folder objects enables getting child folders and files within a single response. This avoids having to make recursive requests.
While $expand is useful, excessive expansion can negatively affect performance. Balance response detail with efficiency based on actual needs.
Optional Query Parameters
In addition to $select, $filter and $expand covered above, other supported parameters include:
- $top – Specifies number of items to return in results. Useful for limiting result size.
- $skip – Skip the specified number of items in the response.
- $orderby – Sorts the result set on the specified property.
- $count – Returns just the total count of matching items. No need to get all items.
Putting It All Together
By combining the supported REST query parameters, targeted and efficient query requests can be constructed to SharePoint. Some examples:
/_api/web/lists/getbytitle('Documents')/items?$select=FileLeafRef,Author/Title&$expand=Author&$filter=FSObjType eq 0 and FileDirRef eq '/Documents/Reports'
This returns documents from the Reports folder, with the file name, author title, filtered for just documents (not folders). Author entity expanded to show title instead of just ID.
/_api/web/lists/getbytitle('Tasks')/items?$select=ID,Title,Status&$filter=Status ne 'Complete'&$top=30&$orderby=DueDate
Requests incomplete tasks from Tasks list, limited to 30 items, sorted by due date.
By combining parameters in this way, the SharePoint REST API provides flexible mechanisms to extract required information efficiently.
