SharePoint Online REST APIs (Part I): Documents

Share the love

In the SharePoint Online REST APIs series, I’ll be sharing the most common APIs I use. I mainly use these APIs in Power Automate, so I’ll base the information in this series on the data you need for a Send an HTTP request to SharePoint action.

The first article of the series is how to interact with documents in SharePoint Online. This is not a comprehensive list; rather a list of calls that I use when I can’t use predefined Power Automate actions. I have used the color red to identify interchangeable values.

Get all the document libraries in a site

Method

URI

GET

_api/web/lists?$filter=BaseTemplate eq 101

BaseTemplate refers to list template type. For document libraries, the number is 101. Microsoft has documentation for the other template types.

Get all files (including folders) in a library

Using the library name

Method

URI

GET

_api/web/lists/GetByTitle('Library Name')/items

Using the library GUID

Method

URI

GET

_api/web/lists(guid'GUID')/items

The first example uses the library name which is the easiest option. I prefer to use the library GUID. This allows you to change the library name and not worry that your code will break. To find the library GUID, go to your SharePoint site. Find your document library and then Library Settings. The library GUID will be displayed in the address bar of your browser (GUID will be displayed between the ‘%7B‘ and ‘%7D‘ characters).

Get all files in a folder

Method

URI

GET

_api/web/GetFileByServerRelativeUrl('/sites/Site Name/Library Name')/Files

Use this call to receive data about all the files that are in a document library folder.

Get all folders inside a library

Method

URI

GET

_api/web/lists(guid'GUID')/items?$top=4000&$select=FSObjType,BaseName&$filter=FSObjType eq 1

FSObjType refers to list file system type. For folders, the number is 1. Microsoft has documentation for the other system types.

The top parameter is optional. In this case, it is going to return the top 4,000 results.

Get document properties using the file path

Method

URI

GET

_api/web/GetFileByServerRelativeUrl('/sites/Site Name/Library Name/FileName.ext')/listItemAllFields>$select=ID,Title

This call is fairly straight forward. You could achieve the same result using the Get Item action in Power Automate. However, this call gives you more flexibility including returning specific columns.

listItemAllFields is optional but the output returns more detailed information about the item.

Get current version of a file using the document ID

Method

URI

GET

_api/web/lists(guid'GUID')/items(23)?$select=FileLeafRef,OData__UIVersionString

If you need to know what version number a document is, use the above call. The main column you want to return is OData__UIVersionString.

Get the version history metadata of a file

Method

URI

GET

_api/web/lists(guid'GUID')/items(23)/Versions?$select=ID,Title&$top=2

The previous call gets the current version number, but if you want to get the metadata that you see in the version history, you can use this call. It is a good idea to use the select parameter to reduce the amount of columns returned.

The top parameter is optional. In this case, I only want to return the last two entries in the version history.

Find a document in a library (folder and ID unknown)

Method

URI

GET

_api/web/lists(guid'GUID')/items?$select=FieldValuesAsText/FileLeafRef&$expand=FieldValuesAsText&$filter=substringof('Filename.ext',FileLeafRef)

If you know a document is inside a library, but only know the filename, you can search for it using the call above. The $select=FieldValuesAsText/FileLeafRef&$expand=FieldValuesAsText is important to be able to search by filename.

Get the E tag of a document

Method

URI

GET

_api/web/GetFileByServerRelativeUrl('/sites/Site Name/Library Name/Filename.ext')/etag

I usually use this call if I’m trying to manipulate the URL of a file. The E tag is important to find the file (without knowing where it resides in the site) so it never changes and is useful in sharing a link to a file.

Update file metadata without affecting the version number

Method

URI

Body

POST

_api/web/lists(guid'GUID')/items(2353)/validateUpdateListItem()

{
"formValues": [
{
"FieldName": "Title",
"FieldValue": "New Title"
},
{
"FieldName": "FileLeafRef",
"FieldValue": "New Filename.ext"
}
],
"bNewDocumentUpdate":true
}

I have covered this call in a previous post, but this is probably the most used API call I use. Even if you choose to increase the version number (set bNewDocumentUpdate to false), you can update metadata on a file that is not possible using a SharePoint Online Power Automate action.


Share the love

2 Replies to “SharePoint Online REST APIs (Part I): Documents”

Leave a Reply

Your email address will not be published. Required fields are marked *