Microsoft Graph API or SharePoint REST API?

The technologies around SharePoint and Office 365 never stop offering a wide range of solutions to access data.

The facts are, in a SharePoint context, on one side, the developers have to choose which gateway they have to take for their developments and on the other side, the number of customers who are interested in the way we access their data even if they are not developers, become increasingly important:

• what are the differences?
• which is the easiest?
• which is the most secure?
• since Microsoft Graph is newer than SharePoint REST API, why do not use it directly for the new developments?
• how to choose between them?

I will try to explain all of this as simple as possible based on my own experience 🙂

SharePoint REST API

Why specify "SharePoint" REST API? 🤓

• API: Application Programming Interface - allows communicating between two software programs through HTTP
• REST: REpresentational State Transfer - an architectural style for web services; essentially used by Microsoft SharePoint
• SharePoint: it is the requested canal/server

If developers want to perform REST API requests on a SharePoint server, they have to use this syntax:

http://myowndomain.com/_api/[site|web|search|...]/[lists|siteusers|...]/...

for a SharePoint On-Premises

https://myowndomain.sharepoint.com/_api/[site|web|search|...]/[lists|siteusers|...]/...

for a SharePoint Online.

As you can guess, you need to know which endpoints you have to use to perform the C.R.U.D (Create, Read, Update, Delete) actions, not to mention that the URL has to correspond to your environment.

Methods

You can use the endpoints with different methods:

• GET: essentially used to get/read data from SharePoint
• PUT: honestly, I do not use it often 😅... It is mostly used to update items of SharePoint but as you will see, you will be able to use the next method (POST) to do this too
• POST: sometimes used to get specific kind of data (taxonomy, view result, etc.) but mainly used to perform the C.-.U.D 😊; accompanied by a header X-HTTP-Method with the value MERGE to update or DELETE to delete something of course

All the requests that send content to SharePoint, have to be authenticated. It is quite simple to get a "DIGEST" from SharePoint solution:

var digest = document.getElementById('__REQUESTDIGEST').value;

from a "classic" development (ex: custom action)

import { SPHttpClient, ISPHttpClientOptions, SPHttpClientResponse } from '@microsoft/sp-http';

...

this.context.spHttpClient.post('[URL]', 
    SPHttpClientConfigurations.v1, 
    headers: { ... }, 
    body: { ... })
    .then((response: SPHttpClientResponse) => {
	response.json().then((responseJSON: JSON) => {
        // the response ...
    });
});

from a SharePoint Framework (SPFx) development.

Examples

Here, a little example to illustrate the simplicity of usage:

1. If you wish to CREATE a SharePoint list, the URL you will use is https://contoso.sharepoint.com/sites/myspsite/_api/web/lists with the POST method and the body message in accordance with what SharePoint expects
2. If you wish to READ the SharePoint list, the URL you will use is https://contoso.sharepoint.com/sites/myspsite/_api/web/lists(guid'00000000-0000-0000-0000-000000000000') with the method GET.
   This request returns the list properties and not the content of it. If you wish to retrieve the content, just add items at the end of the URL
3. If you wish to UPDATE the SharePoint list, the URL you will use is https://contoso.sharepoint.com/sites/myspsite/_api/web/lists(guid'00000000-0000-0000-0000-000000000000') with the method POST and the header X-HTTP-Method with the value at MERGE
4. If you wish to DELETE the SharePoint list, the URL you will use is https://contoso.sharepoint.com/sites/myspsite/_api/web/lists(guid'00000000-0000-0000-0000-000000000000') with the method POST and the header X-HTTP-Method with the value at DELETE

Links

Here, the principle:

Get to know the SharePoint REST service

Basics of using the SharePoint REST service to access and update SharePoint data, using the REST and OData web protocol standards.

Microsoft Docsspdevdocs

Here, some examples of usage provided by Microsoft:

https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-rest-reference/jj860569(v=office.15)

Simple, isn't it? Your turn now 👍🏻

Microsoft Graph

is a RESTfull API (ooohh!! just like SharePoint REST API) that allows accessing the SharePoint data but not only! With Microsoft Graph, you can access the wide resources provided by your Microsoft 365 Tenant.

[note]Note

It also means that Microsoft Graph is only available for a SharePoint Online environment. If you have a On-Premise environment, you cannot use it - only SharePoint REST API can be used.

Just like SharePoint REST API, the concept is exactly the same; the main difference is the URL:

https://graph.microsoft.com/v1.0/sites/{site-id}

Only one point (main URL) to access the whole data!

Unlike SharePoint REST API, the developers have to explicitly identify the needed access used by the app and an administrator has to approve the access request(s) from the API management available from the SharePoint admin center.

Examples

Here, a little example to illustrate the usage:

1. If you wish to CREATE a SharePoint list, the URL you will use is https://graph.microsoft.com/v1.0/sites/00000000-0000-0000-0000-000000000000/lists with the POST method and the body message in accordance with what SharePoint expects
2. If you wish to READ the SharePoint list, the URL you will use is https://graph.microsoft.com/v1.0/sites/00000000-0000-0000-0000-000000000000/lists/00000000-0000-0000-0000-000000000000 with the method GET.
   This request returns the list properties and not the content of it. If you wish to retrieve the content, just add items at the end of the URL
3. If you wish to UPDATE the SharePoint list... I am not sure you can (yet)
4. If you wish to DELETE the SharePoint list, the URL you will use is https://graph.microsoft.com/v1.0/sites/00000000-0000-0000-0000-000000000000/lists/00000000-0000-0000-0000-000000000000 with the method POST and the header X-HTTP-Method with the value at DELETE

Links

Microsoft documentation about Microsoft Graph with SharePoint:

Working with SharePoint sites in Microsoft Graph - Microsoft Graph v1.0

The SharePoint API in Microsoft Graph supports the following core scenarios:

Microsoft Docsrgregg

Microsoft provides Graph Explorer; a tool to connect you to your environment, try your own requests or some samples:

Graph Explorer - Microsoft Graph

The Microsoft Graph explorer is a tool that lets you make requests and see responses against the Microsoft Graph

Microsoft GraphO365devxmicrosoft.com

Conclusion

Microsoft Graph is young and has less documentation than SharePoint REST API; for the developers, the research and development could be a little bit longer.

Because Microsoft Graph is relatively young, the endpoints are limited. Currently (October 2, 2019), the endpoints available to work with SharePoint are:

• Access to SharePoint sites, lists, and drives (document libraries)
• Read-only support for site resources (no ability to create new sites)
• Read-write support for lists, listItems, and driveItems
• Address resources by SharePoint ID, URL, or relative path

Microsoft Graph is "more secure" than SharePoint REST API because the resources accesses are explicit into the code and approved by a SharePoint administrator and/or the users.

SharePoint REST API is essentially based on the SharePoint user context whereas Microsoft Graph is based on the entire environment.

Microsoft Graph can be more greedy than SharePoint REST API for little or a lot of actions on a SharePoint context only -> it is bringing in an elephant to kill a mouse, isn't it?

Microsoft Graph becomes useful when you wish to link several resources types in one point (like Delve does).

I hope this post has clarified some aspects in order for you to choose the best solution by yourself.

Hoping this post will help you 😉

• Tags:
• SharePoint
• Getting Started
• Development
• Microsoft 365
• Security
• SharePoint Framework
• JavaScript
• Microsoft Graph