Access OneDrive for Business using the SharePoint 2013 APIs

  • Article

OneDrive for Business , a personal cloud library for business, is a place where users can store files and documents, sync them with their devices, and share them with others. It comes as a part of SharePoint Server 2013 or SharePoint Online (Office 365). Essentially it’s a SharePoint Document Library under the covers, so you can access it just like any other document library in SharePoint 2013 using the SharePoint APIs. Whether you use the client-side object model (CSOM) or Representational State Transfer (REST)—it’s your choice. In this post, learn how to construct the REST URLs to access files and folders in OneDrive for Business.

From a user’s perspective, to access your OneDrive for Business library, you simply click OneDrive in the Office 365 menu bar, as shown in Figure 1.

Figure 1. Office 365 menu bar    
Figure 1. Office 365 menu bar

Or you can always navigate directly there using this URL pattern:
https://YourO365DomainHere-my.sharepoint.com/personal/
    YourUserName_ YourO365DomainHere_onmicrosoft_com/.

But that’s from the end-user perspective. How do you access OneDrive for Business as a developer? In this example, we will use REST.

Note: If your Office 365 site is set up to use a custom domain—for example, contoso.com—your MySite URL will be of the pattern, https://contoso-my.sharepoint.com/personal/YourUserName_ contoso_com/.

Start with the basics

  1. Sign in to your Office 365 SharePoint site, and navigate to your OneDrive for Business library using one of the two methods mentioned above.
  2. Click the Shared with Everyone folder and upload a document. For this example, the document name is myDocument.docx.
  3. To use the REST API to view the information on the uploaded document, construct a URL with the following pattern:
    https://YourO365DomainHere-my.sharepoint.com/personal/
        YourUserName_YourO365DomainHere_onmicrosoft_com/_api/web/
        GetFileByServerRelativeUrl('/personal/YourUserName_YourO365DomainHere_onmicrosoft_com/
            Documents/Shared with Everyone/myDocument.docx')
  4. Copy/paste it into your browser. The XML returned should look like this: Figure 2. Example of XML returned by the REST APIFigure 2. Example of XML returned by the REST API
  5. To download the document, append /$value to the URL. When prompted to save the file, name it myDocumentDownload.docx, and save it.

Work with documents and other files as “items”

  1. For definitive read/write guidance, see Working with lists and list items with REST on MSDN.
  2. To experiment, upload a couple of files to the root Documents folder in your OneDrive for Business library. Now you can test out a few REST read calls in your signed-in browser.
  3. Using this URL pattern:
    https://YourO365DomainHere-my.sharepoint.com/personal/
        YourUserName_YourO365DomainHere_onmicrosoft_com/_api/web/
    Append lists/Documents/items/ to it. Here you will get all the items.
    1. To get the metadata for a particular item, modify items/ to items(n)/ where (n) is the specific item number you want to view.
    2. To see the metadata for the file, append file/ (for example, items(n)/file/ )
    3. To download the file, append $value (for example, items(n)/file/$value)
  4. You can also use in place of the above pattern lists/GetByTitle('Documents')/ …, and the API will return the same results.

Work with folders and files

  1. Files are often nested in folders, and you may need to drill down into the folder structure; or you may want to represent the folder structure and files in a user interface (UI). Using the following REST calls, you can also work with folders and files in a more logical way than just the “items(n) ” sequential location as the pattern shown above. This is where getting folders by relative URL and subsequently enumerating all the files within a folder is really handy.
    For definitive read/write guidance, see Working with folders and files with REST on MSDN.

  2. Assume the OneDrive file structure shown in Figure 3, where you have both folders and documents at the same level. Figure 3. SkyDrive file structure with folders and documents at the same level
    Figure 3. OneDrive file structure with folders and documents at the same level

  3. To retrieve all the folders, you will use GetFolderByServerRelativeUrl with the following URL pattern:
    https://YourO365DomainHere-my.sharepoint.com/personal/
        YourUserName_YourO365DomainHere_onmicrosoft_com/_api/web/
    To this URL, append GetFolderByServerRelativeUrl('/personal/YourUserName_YourO365DomainHere_onmicrosoft_com/Documents')/folders/ .
    All the folders will be returned. You can then subsequently use the ServerRelativeURL property for each folder to continue to “walk down” each folder until you reach its end node. Figure 4. ServerRelativeUrl property of a folderFigure 4. ServerRelativeUrl property of a folder

  4. Likewise, if you want to return metadata about all the files in a folder, simply replace folders/ with files/ , and all the files will be enumerated. Figure 5. ServerRelativeUrl property of a file
    Figure 5. ServerRelativeUrl property of a file

    Then, if you want to retrieve the file, use the GetFileByServerRelativeUrl URL pattern, described in the first section above, with /$value appended to the URL.

The above URL patterns show how to construct the REST calls for use in the browser for simplicity. However, you can readily implement these URL patterns in your code.

For example, if you are developing an app for SharePoint, the app can call into a user’s MySite site collection and access their OneDrive for Business documents using REST or CSOM.

The REST call to get to the file would be:
https://YourO365DomainHere-my.sharepoint.com/personal/
    YourUserName_YourO365DomainHere_onmicrosoft_com/_api/web/
    GetFileByServerRelativeUrl('/personal/YourUserName_YourO365DomainHere_onmicrosoft_com/
        Documents/Shared%20with%20Everyone/myDocument.docx')/$value

To programmatically get the OneDrive for Business URL for the signed-in user, you can make a call to the user Profile service:
https://YourO365DomainHere-my.sharepoint.com/\_api/
    SP.UserProfiles.PeopleManager/GetMyProperties/personalURL/

Remember, your app for SharePoint needs to request the right set of permissions in the app manifest to access OneDrive for Business content—for example, AllSites.Read—and if using the User Profile service: Social.Read. When you request a token from Access Control Service (ACS), make sure you have the right audience. In order to call OneDrive for Business, you need a token whose target audience is https://YourO365DomainHere-my.sharepoint.com/ . Also remember to encode all the query parameters in the URL.

This post does not detail these calls for CSOM, but the CSOM equivalents are available: see the CSOM, JSOM, and REST API Index. Other valuable resources are the articles on how to complete basic operations using CSOM and JSOM, and getting started with SharePoint 2013 REST.

Lastly, for sample code, download the Apps for SharePoint sample pack, which provides examples across C#, REST, and JavaScript. It contains useful samples, including:

Enjoy!

Yina Arenas, Program Manager, APPS PM

Donovan Follette, Sr. Technical Evangelist, Developer & Platform Evangelism