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!

11 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
    3. If you run a query like https://graph.microsoft.com/v1.0/me/drive/items/01BC3OZW2DYVPRO33W5FCIEDO36C7O7HQY/workbook?$whatif you see that the Excel handling is done by Office Online Server, not SharePoint. https://euc-excel.officeapps.live.com/x/_layouts/xlrestinternal.aspx?....

      So this is as exptected. You could probably still use the old SP Excel REST endpoint, but this is according to docs not recommended, as Graph should be used. Haven't tested if it even still works.

      Delete
    4. Yes, the old endpoint "/_vti_bin/ExcelRest.aspx" still works. I'm using it now but it is a bit slow and I was hoping to replace it with this new endpoint (without having to ask the user to click button and accept app access to the Graph API).

      Delete
  3. Mikael, I'm curious how you could see that https://graph.microsoft.com/v1.0/me/drive/items/01BC3OZW2DYVPRO33W5FCIEDO36C7O7HQY/workbook was being handled by Office Online Server?

    I'm actually trying to find more information about ../xlrestinternal.aspx and thought this maybe a good way to go about it


    ReplyDelete
    Replies
    1. Figure might as well follow up to my own question here, in case someone else is looking and happens upon this thread.

      If your setup calls Online Office Server directly (via WOPI) and you need some excel data via rest, you can use the same api syntax as you would with the graph apis by passing it in the wdRestPart query param to that ..../xlrestinternal.aspx endpoint

      ex http://{oosserver}/x/_layouts/xlrestinternal.aspx?wdRestPart=_api/worksheets(Sheet1)/range(address=A1:I17).....

      Delete
    2. The ?$whatif part shows what the Graph is calling underneath, and is how you can tell what handles the query.

      Delete
    3. Oh, wow, thanks. I don't know how I overlooked that ?$whatif in your original post. Just tried in Graph Explorer with ?$whatif appended, and I see the whole explanation including that wdRestPart.

      This is pretty great, now I can test my queries in the cloud in Graph Explorer and then transfer them to our on-premise OOS/wopi implementation, using that /xlrestinternal.aspx endpoint, which has 0 documentation anywhere.

      Delete