Office 365 and SharePoint Online API Guidance for Developers

Editor’s note: This is a guest post by Andrew Connell, Founder of Voitanos. For more information about Andrew, visit his website and follow him on Twitter: @andrewconnell.

THE CONFERENCE MODERN WORKPLACE PROS CAN’T MISS

---

Office 365, including SharePoint Online, is Microsoft’s enterprise collaboration and messaging platform. Millions of businesses use Office 365 for their company email, messaging, collaboration, intranets, and project management. With so much company information and assets in Office 365, developers working as employees or consultants for the company, as well as vendors, want to leverage this data in custom applications to provide value to the business.

The good news is that Microsoft provides developers plenty of APIs and SDKs to interact with Office 365 and related services… but that also presents a challenge. Unless you are familiar with the options, you may not know which is the best one. It is like walking into a kitchen without much cooking experience and having someone say “grab a pot”, only to see 10 different pots in the cabinet. Which one is the best one to saute vegetables?

In this article I will cover the different Office 365 and SharePoint APIs and SDK options available to developers and some scenarios on when to use them. While this article will not provide an exhaustive list, it should provide developers with a good starting point of the most popular options.

SharePoint

SharePoint has a few different options for interacting with SharePoint. The next few sections will detail these options. However, before selecting one of these options for your current project, make sure you read the whole article as the Microsoft Graph section may be more applicable to what you want to do.

SharePoint REST API

The primary way custom applications have been talking to SharePoint since SharePoint 2010 and SharePoint 2013 has been the SharePoint REST API. The SharePoint REST API provides developers access to not just the data within SharePoint site collections, sites, lists and libraries, but also to the settings and configuration options for these resources. Developers can even create content types and site columns in the sites. These are the most common things, but

This is a REST API that conforms to the generally accepted ODATA specification for REST APIs. Therefore developers familiar with the ODATA specification if they have worked with using other products, including the format and grammar requirements for queries as well as how to submit data, will feel right at home working with the SharePoint REST API.

SharePoint Online, like all Microsoft Cloud Services including Office 365, is secured using Azure Active Directory (aka: Azure AD / AAD). When a user accesses their mailbox in Exchange Online or their company intranet in SharePoint Online, the first step is to authenticate with Azure AD.

The SharePoint REST API shares the same authentication / authorization dependency with Azure AD in the sense that every custom application must first be registered and then obtain an OAuth 2 access token from Azure AD that will be included in every request to the SharePoint REST API. Authentication in Azure AD is based on OAuth 2 and therefore adheres to generally accepted industry standards.

This adherence to generally accepted open standards, both with ODATA for the format of the REST API and OAuth 2 for authentication, developers can use any technology stack, infrastructure and language they choose to communicate with the SharePoint REST API.

For more information on the SharePoint REST API, refer to the official documentation on MSDN: https://msdn.microsoft.com/library/office/jj860569(v=office.15).aspx

SharePoint SDKs (CSOM & JSOM)

Many times developers would prefer to work with a software development kit (SDK) instead of raw REST APIs. An SDK can rationalize concepts and simplify certain tasks such as authentication, or abstracting away the plumbing required when making REST calls.

When Microsoft shipped SharePoint Server 2010, they introduced a client side SDK, referred to as the client side object model (CSOM). The CSOM was intended to be used for .NET Framework authored applications hosted external to SharePoint. At the time, the CSOM provided more endpoints and capabilities than the SharePoint REST API.

However in SharePoint 2013, Microsoft significantly invested in the SharePoint REST API and retooled the CSOM so it called the REST API rather than a dedicated endpoint. This means that capabilities of the CSOM and SharePoint REST API are mostly equivalent to today and it is now down to a personal preference by developers.

Like the SharePoint REST API, the SharePoint SDKs are secured using the same Azure AD authentication flows, but they provide some functions to simplify the authentication process.

Microsoft also offers a JavaScript implementation of the CSOM, referred to as the JSON, which is intended to be used by client-side solutions hosted within SharePoint.

For more information on the CSOM & JSOM, refer to the official documentation on MSDN: · CSOM: https://msdn.microsoft.com/en-us/library/office/jj193041.aspx · JSOM: https://msdn.microsoft.com/library/office/jj193034(v=office.15).aspx

---

Like what you read? Be sure to subscribe to our blog to stay in the fold for all things Office 365, SharePoint and more!

---

SharePoint Search REST API

One special case when it comes to SharePoint is the SharePoint Search REST API. Developers can use this to add search functionality to custom applications that support REST requests. The SharePoint Search REST API accepts queries using either the Keyword Query Language (KQL) or FAST Query Language (FQL).

Like the SharePoint REST API, the SharePoint SDKs are secured using the same Azure AD authentication flows, but they provide some functions to simplify the authentication process.

For more information on the SharePoint Search REST API, refer to the official documentation on MSDN: https://msdn.microsoft.com/library/8a4f7863-e4c1-4099-9189-a1894db36930%28office.15%29.aspx

SharePoint PnP

Another option that developers should be aware of are resources provided by the SharePoint Patterns and Practices (PnP) group. This is a group run by Microsoft that includes not just guidance documents, but also extensions to the SharePoint CSOM and JavaScript libraries for developers. Most of the work in the PnP is based on comes from real-world customer interactions bridging gaps in on-premises SharePoint deployments to performing the same tasks in SharePoint Online.

For more information on SharePoint PnP and the resources they offer, refer to their subsite on the Office developer site: https://dev.office.com/patterns-and-practices

Office Graph API

Leveraging the power of Office 365, search and cloud computing, Microsoft introduced the Office Graph to expose trends and relationships between people within an organization based on their activity. I like to think of the Office Graph as a specialized “Office 365 insights search” service, one that you can only query.

The Office Graph is the engine that drives Office Delve. Delve helps people “discover new, relevant information and people based on the intelligence of who [they] work with and content [they] work on.” (ref: https://products.office.com/en-us/business/explore-office-delve).

The two primary endpoints the Office Graph API offers are TrendingAround (items that are popular in your circle of colleagues) and WorkingWith (people whom you frequently interact with). It also exposes a person’s manager and collection of colleagues.

Like the other API options previously covered, the Office Graph API is secured using the same Azure AD authentication flows, but they provide some functions to simplify the authentication process.

For more information about the Office Graph REST API, refer to the official documentation on MSDN: https://msdn.microsoft.com/en-us/office/office365/howto/query-office-graph-using-gql-with-search-rest-api#running-graph-queries-against-sharepoint-2013

Microsoft Graph

Now that I have covered the non-exhaustive list of the various Office 365 and SharePoint related API endpoints list in this article, there is one thing you should consider:

Forget about all of them except the SharePoint PnP one. Why?

Because the Microsoft Graph is the single Office 365 API endpoint you should first consider for all your projects. The Microsoft Graph is intended to be the one endpoint for Microsoft Cloud Services, including Office 365 and other services.

The Microsoft Graph enables developers to access data from multiple Microsoft Cloud services including:

• Azure AD (for users and groups)
• Office 365
• SharePoint Online
• Exchange Online
• OneDrive for Business
• OneNote
• Planner
• Excel
• OneDrive Consumer
• Outlook.com

This single endpoint has a few significant advantages to using the specific APIs available from the previously mentioned services.

First, it acts as a proxy to the other endpoints behind it. This means developers do not need to hunt for the different endpoints and documentation for each service. The Microsoft Graph has a single, well-known, endpoint: https://graph.microsoft.com.

Second, because it is a single endpoint proxy to the other services behind it, developers only need to register an application one time, users need to grant the application consent one time, and the application needs to obtain a single OAuth 2 access token to talk to the various services.

Third, because it is a single endpoint, it can allow developers to navigate between entities and relationships even if they are in different systems. For instance, the Microsoft Graph will allow you to get access to a user (from Azure AD) and see their mail (from Exchange Online), notebooks (from OneNote), tasks (from Planner) and files (from OneDrive for Business). Without the Graph, this would require five (5) different authentication prompts to obtain tokens for the different services and multiple round trips to the server to get the data.

Like the Microsoft Cloud Services it exposes, the Microsoft Graph is OData compliant and leverages Azure AD for authentication. The Microsoft Graph also leverages the Office Graph API for relationships and insights between users.

In short, there’s very little reason to use any of the specific Microsoft Cloud Service specific APIs when the Microsoft Graph has so much to offer!

Microsoft Graph REST API

The Microsoft Graph, like other Microsoft Cloud Services, is accessible via an OData compliant REST API. This means developers can leverage any technology stack, infrastructure and language to access the Microsoft Graph endpoints.

Microsoft Graph SDKs

Developers who prefer the SDK approach will be very happy to know that the Microsoft Graph also has multiple SDKs for different platforms and technologies including:

• Android
• Angular
• ASP.NET MVC
• iOS
• JavaScript
• PHP
• Python
• Ruby
• Universal Windows Platform (UWP)
• Xamarin

The Microsoft Graph has its own, very robust site filled with documentation, code samples, SDKs, and a playground to explore its capabilities with either test data or live production data from your environment. You can get more information about the Microsoft Graph at: https://graph.microsoft.io.

---

Secure your Microsoft 365 collaboration spaces with Policies and Insights!

---

Conclusion

In this article, I listed some of the many different APIs and SDKs developers can use to create custom applications. While the different Microsoft Cloud Services, including those within Office 365, have various REST APIs and SDKs, I recommend all developers to first consider the Microsoft Graph to see if they can access and achieve what they are looking to do before looking at the service specific endpoints.

Webinar

Want even more guidance on SharePoint customization and SharePoint Framework? Join me for a webinar at 2pm ET on Thursday, September 7 with AvePoint’s D’arce Hess to discover best practices and tips for choosing the right API and/or SDK for your custom applications.