Monday, January 7, 2019

Introducing the SharePoint REST API v2.0

image

For as long as REST has been supported in SharePoint the endpoint programmers have used is http://server/site/_api/ or https://contoso.sharepoint.com/_api for those of us who left on-premises years and years ago.

Now Microsoft has given us a v2 endpoint for the REST API. This has sort slipped under the radar, but I’m happy to announce that it’s there, it’s supported, and you can use it!

But wait, what is this v2 API, and why should I care or use it?

If you have been reading the SharePoint 2016 OneDrive REST documentation or if you have followed how the Microsoft Graph REST endpoints for SharePoint have evolved, you have your answer right there. For any SharePoint related Graph URL, you can instead make a call directly to SharePoint as seen in the below table.

Graph URL SharePoint URL
https://graph.microsoft.com/v1.0/sites https://{tenant-name}.sharepoint.com/_api/v2.0/sites
https://graph.microsoft.com/v1.0/drives https://{tenant-name}.sharepoint.com/_api/v2.0/drives
https://graph.microsoft.com/v1.0/drive https://{tenant-name}.sharepoint.com/_api/v2.0/drive
https://graph.microsoft.com/v1.0/lists https://{tenant-name}.sharepoint.com/_api/v2.0/lists

Which means the documentation for the SharePoint v2 REST API is located at https://docs.microsoft.com/en-us/graph/api/resources/sharepoint?view=graph-rest-1.0 and https://docs.microsoft.com/en-us/graph/api/resources/onedrive?view=graph-rest-1.0. The 2016 reference can be found at https://docs.microsoft.com/en-us/onedrive/developer/rest-api/getting-started/sharepoint-server-2016?view=odsp-graph-online.

When it comes to the Microsoft Graph API’s, remember that they basically are proxies to whatever underlying API the services expose internally – in the case of SharePoint, those API’s are located at _/api/v2.0/.

As I’m no longer doing on-premises SharePoint myself you have to test these API’s yourself if needed with SharePoint 2016 and SharePoint 2019 to see which ones work.

Why would I want to use the v2 REST API?

For most scenarios you will find the same capabilities in the v1 and v2 REST API’s, but the Graph has some nifty features here and there, some of convenience and some which only exists in the Graph (as far as I know). I’ll leave it up to you as a reader to compare the API’s :)

If you for example have a Graph REST query you like using with SharePoint, the biggest advantage is that you can now call this API directly within SharePoint in a SharePoint security context, without having to proxy it via the Microsoft Graph and an extra layer of authorization. For me, SPFx comes to mind as a good candidate where I now can get the thumbnail photo for a file directly within SharePoint following the documentation at https://docs.microsoft.com/en-us/graph/api/driveitem-list-thumbnails?view=graph-rest-1.0.

https://{tenant-name}.sharepoint.com/_api/v2.0/drive/items/{item-id}/thumbnails/{thumb-id}/{size}

As Chaks demonstrated in his blog post Displaying file thumbnails from a SharePoint library in PowerApps, you may also use the v2 API in Microsoft Flow, which makes authorization easier, as you can use the SharePoint HTTP action.

Enjoy!

4 comments:

  1. Cool. Great article. Didn't realise this was out

    ReplyDelete
  2. Very interesting. It would have been very useful for working with Excel files, but it doesn't seem that Excel operations are enabled here, even though they are documented as "You can access a workbook through the Drive API" according to https://docs.microsoft.com/en-us/graph/api/resources/excel?view=graph-rest-1.0

    I get a successful JSON response using a URL like

    https://xxx.sharepoint.com/sites/demo/intranet/_api/v2.0/drive/items/0134567894PDKEWEPAANCZL2TNDN7IHJT3

    but if I try

    https://xxx.sharepoint.com/sites/demo/intranet/_api/v2.0/drive/items/0134567894PDKEWEPAANCZL2TNDN7IHJT3/workbook

    I get Microsoft.SharePoint.Client.ResourceNotFoundException.

    If I'm testing this correctly. It is an xlsx file.

    ReplyDelete
    Replies
    1. And the same call works using the Graph endpoint? Could perhaps be that the workbook endpoint is graph specific. Not tested this in detail myself.

      Delete
    2. I can confirm, the Excel endpoint although a "graph" to a sharepoint drive item (or onedrive drive item) if it is an excel workbook, is still specific to the graph and not an extension of Sharepoint, ergo you cannot get to it via the SharePoint REST apis

      Delete