SharePoint APIs are essential tools for developing custom solutions, integrations, and applications within the SharePoint ecosystem, Microsoft's collaboration and document management platform. APIs allow developers to interact with SharePoint data and services in a variety of ways, extend their functionality, and facilitate integrations with other software and business process automation. In this article, we are going to give a general overview of what they are, how they work and what their main characteristics are.
API stands for Application Programming Interface, or an application programming interface: a software intermediary that allows two applications to communicate with each other. APIs are an accessible way to extract and share data within and across organizations.
Modern APIs adhere to specific standards (typically HTTP and REST), which allow them to be developer-friendly, easily accessible and understandable and are treated much more than in the past as consumer products by audiences such as mobile app developers.
They are documented and versioned in such a way as to allow users to have clear expectations about their maintenance and life cycle and being much more standardized than in the past, the focus on performance and security of the same has increased significantly over time.
SharePoint APIs are no exception and allow you to interact with the data and functionality of the platform to create customized solutions, automate processes, improve content management, site administration, permission control and manage communication between Microsoft SharePoint and other applications of the Microsoft 365 environment in a fluid and efficient way.
To get an idea of what they are in practice, let's see what they are, what differentiates them and how they work.
There are currently two types of APIs available for SharePoint: one is the SharePoint REST API and the other is the Microsoft Graph API.
The Graph API and the REST API, while based on the same architecture, are two different ways of accessing data from SharePoint and other Microsoft 365 services. The main difference between the two is that the Graph API is a more general, unified API that can access data from various Microsoft 365 services, while the SharePoint REST API is designed to work specifically with SharePoint sites and content.
The Graph API provides a consistent developer experience for authentication, documentation, SDKs, and offers functionality such as change notifications, delta queries, and batch requests. In addition to covering most of the common scenarios for working with SharePoint sites, lists, folders, items, and documents, Graph also supports identity-based access, meaning that you can use the same URL to access different resources based on the user's permissions.
The downside is that it doesn't support some of the specific SharePoint functionality, and it may have some latency or performance issues compared to the SharePoint REST API, since it's a proxy for the actual SharePoint API.
The SharePoint REST API, on the other hand, provides greater functionality and control over specific SharePoint functionality, such as site settings, site templates, workflows, search, etc.
It may have better performance and responsiveness than the Graph API, since it accesses the SharePoint data source directly, but keep in mind that the use of the REST API requires different endpoints and authentication methods for the different Microsoft 365 services, which can increase the complexity and maintenance of the app and uses function-based access methods, which means that it is necessary to know the exact name and parameters of the function to access a specific resource.
So which one to choose? It basically depends on what your needs and preferences are and how much extensive control over SharePoint functionality you want. However, it is necessary to bear in mind that in recent times Microsoft has been pushing very hard on the use of Graph in the perspective of the modern Redmond house policy that wants maximum integration between all the products of the Microsoft 365 digital work environment.
Given a general look at what types of APIs are available for SharePoint, let's now look more specifically at what characterizes them individually. Let's start with the SharePoint REST API.
This is specifically designed to interact with the data and functionality of the Microsoft collaboration platform. This means that it is optimized to provide direct and detailed access to specific SharePoint data and operations, such as lists, documents, metadata, and site settings.
Through its use, developers therefore have direct and detailed control over SharePoint resources, allowing them to perform specific operations optimized for the needs of the application, without having to worry about additional levels of abstraction that could complicate development or negatively impact the performance of the solution you want to implement.
REST (acronym for Representational State Transfer), is an architectural style that guides the design and development of network systems. One of the main advantages of REST APIs is that they provide a great level of flexibility. The data is not tied to resources or methods, so REST can handle different types of calls and return different data formats.
The REST architecture focuses on the concept of resources, which are identified by unique URLs, and is based on the standard Open Data Protocol (OData) allowing developers to perform basic creation, reading, updating and deleting (or CRUD) operations through a RESTful HTTP request.
In the context of SharePoint, resources can be items in a SharePoint list, documents in a SharePoint library, or even the SharePoint site itself. By interacting with these resources using HTTP requests, clients can retrieve information, make changes, and perform other actions.
SharePoint resources, such as lists, libraries, or sites, are exposed through specific URLs called endpoints. These endpoints represent entry points for interacting with SharePoint resources using the REST API.
To work with the SharePoint REST API, you must create and send HTTP requests to the appropriate SharePoint API endpoints, with all the necessary information inside them (such as the destination endpoint, headers, and sometimes request bodies). Requests are sent to the SharePoint server, which processes them and returns responses. These responses contain the requested data, confirmation of a successful operation, or error messages in case of problems.
These HTTP requests use several methods to perform basic operations:
For example, if we make an HTTP GET request to this endpoint, the request will allow us to retrieve a list of items from a SharePoint site:
https://example.sharepoint.com/_api/web/lists/
getbytitle('ListName')/items
The SharePoint REST API provides functionality that matches various client object models, including:
Each client object model allows you to interact with all SharePoint entities, such as lists, SharePoint libraries, and many other types of content.
We created intranet.ai, which now has over 200 installations worldwide. It is the ready-to-use and customizable solution for digitizing the processes and communication of any company. We'll help you:
Contact us if you have a SharePoint Online project in mind.
Let's now take a closer look at the second option discussed above (and currently the one preferred by Microsoft for development in its digital environment), namely the Microsoft Graph API.
Designed to provide a consistent and simplified experience for developers who want to integrate Microsoft 365 functionality and other cloud resources into their projects, the Microsoft Graph API provides a single API endpoint that can be used to access data from multiple services (including of course also SharePoint Online), making it easier for developers to create cross-platform applications that perform a variety of tasks, such as reading and writing emails, managing calendars, accessing files and folders, and that work without problems on different devices.
Like the REST API, the API follows the Open Data Protocol (OData) standard, allowing developers to perform CRUD operations on Microsoft SharePoint entities using HTTP commands such as GET, POST, PUT and DELETE.
In the specific context of SharePoint, the Microsoft Graph API offers a powerful way for developers to interact with the data and functionality of SharePoint sites and other related services and greatly enriches the operation of intranets based on SharePoint Online.
An example of this enrichment of the functionalities dedicated to intranets is the possibility of Expand the people directory, taking advantage of the information that Graph makes available and that comes from employees' Microsoft 365 accounts. The advantage of this integration lies in the fact that personal data is transferred in real time from Microsoft 365 to the intranet, automatically updating the profiles present in the latter.
Developers can also take advantage of advanced features such as change notifications to be notified when SharePoint data changes, delta queries to retrieve only recent changes, and batch requests to optimize API call performance.
The API allows developers not only to access SharePoint data, such as sites, lists, documents, folders, and more, using standardized API requests, but because the Microsoft Graph API unifies access to SharePoint data together with other Microsoft services (such as Outlook, OneDrive, Teams, and Azure Active Directory), developers can also create applications that integrate data from different sources without having to manage multiple API endpoints and that work on a wide range of platforms and devices, including smartphones and tablets.
As far as search functionality is concerned, both the SharePoint REST Search API and the Microsoft Graph API offer different features, advantages and limitations depending on your needs.
The choice between the two depends on the specific requirements of the application and the scope of the research. For highly specialized and detailed searches in SharePoint content, the SharePoint REST Search API is often preferred. For scenarios that require the integration of data from different Microsoft 365 services, the Microsoft Graph API is generally the best choice. But let's look at their characteristics in a little more detail.
As we have already mentioned above (and as can be seen from the name), the SharePoint Rest API is optimized for SharePoint and allows you to perform search queries on SharePoint content, such as documents, lists, sites and all types of files that can be stored in its spaces, offering specific advanced options for customizing queries, including refinements, sorting and complex logical operators and (in some cases) it can offer better performance for specific SharePoint searches than Graph's unified API.
The request is usually made using the HTTP GET method, of which we had given a small example in the section dedicated to the characteristics of the REST API and which we will now try to learn more about.
GET http://server/_api/search/query? query_parameter
GET requests like the one in the example are suitable for relatively simple queries. More complex requests can be assembled as JSON documents containing the appropriate key/value pairs for each element of the request.
The answers can be limited to a fixed number of documents, or you can choose to paginate the response data, loading blocks of results as users move from page to page or adding new results as they scroll through a single-page web application.
Even though APIs have their own syntax, you still need to think about KQL (Keyword Query Language) and FQL (FAST Query Language) when constructing query terms. These allow you to choose the documents returned in the result set. Using the GET API you are limited to a single filter. To use more, for example, you can use POST to send an array of FQL filters to the search server.
Unlike most search environments, the SharePoint API offers many options for customizing results and ensuring that roles and other access control mechanisms are applied, as well as giving administrators the ability to apply a certain level of editorial control over results to set how they are ordered and displayed.
A useful feature is the option that allows you to return suggested queries based on what other users have searched for. The SharePoint Search API offers a simple Suggest endpoint for this, using parameters to provide possible search terms that can trigger a suggestion. These are probably the user's current search terms and can help the user quickly refine queries before or after a search is performed.
Although there is no end of life date for the current existing search APIs, given Microsoft's migration project to a unified API for the entire Microsoft 365 environment, the new features will only be available through the Microsoft Graph API.
As part of this change, all searches will go through a single API. This means that the code written for SharePoint will also work with other Microsoft 365 services, wherever there is a search index. Using a common search API for all of your Microsoft 365 content makes sense, especially given Microsoft's focus on generative AI and large language models.
The establishment of a common search API for all Microsoft 365 services represents a long-overdue step in managing company documentation. With good search capabilities and effective metadata indexing, there's really no need for an artificial structure to navigate through files. Instead, the information is provided at the necessary time from a single index, providing a transparent bridge between the spaces of the various applications.
The Microsoft Graph API is a typical REST API, which uses POST with a JSON payload. Each JSON payload consists of a set of requests, which are executed against entities and which contain queries. Queries are strings and can be used to define the scope of your requests. This way, you can include specific SharePoint sites in your tenant or exclude sections of your tenant that you don't want to be searched for.
Once you have built your basic query JSON, you can start refining its operation, for example by sorting the results using familiar pagination techniques and applying additional filters, such as specific time windows on which to base your search.
It should be mentioned that you are not limited to the hierarchical structure of Graph's queries, since you can use the Keyword Query Language (KQL) as part of your queries. The queries can then be aggregated, offering the ability to build complex queries that work on different Microsoft 365 entities. This approach allows you to collect not only the documents related to a query, but also, for example, relevant emails and lists of people.
In addition to a library of predefined connectors for your applications, Microsoft provides tools that you can use to create your own custom connectors for custom applications, or to work with legacy data on mainframes or minicomputers.
Think of working in the background of Microsoft Graph as a dynamic, constantly updated index of your non-relational data. As new content is stored in Microsoft 365 and on platforms such as SharePoint Online, this index updates automatically and makes the content available throughout your Microsoft 365 tenant for all business users.
Another good reason to use a single search API is that it can help ensure that regulated data is granted access only to authorized users. Wrapping Microsoft Graph queries in a role-based authentication scheme helps ensure that access to data is recorded, monitored, and that users can access only the data allowed for their role or group.
Microsoft is currently working to replace legacy authentication processes (username and password authentication) for its Microsoft 365 services. This step was taken by the Redmond company to improve the general security of its software, as legacy authentication is now far too vulnerable to malicious attacks aimed at stealing user login data.
Both the SharePoint REST API and the Microsoft Graph API use OAuth 2.0 as their standard authentication method. OAuth 2.0 reduces the risk of compromising credentials compared to authentications based on username and password and allows granular authorization management, specifying exactly which resources and operations an application can access using a system based on short-term access tokens that can be revoked at any time, which greatly improve overall data security.
While the basic authentication process is similar for both APIs, Microsoft Graph API offers, as we've already seen, a unified point of access to a wide range of Microsoft 365 services, providing greater flexibility and integration.
Authentication for the SharePoint REST API can be carried out using different methods, but with the transition to better security protocols mentioned above, OAuth 2.0 has become the recommended standard.
First, you must register your application in Azure Active Directory (AAD). During registration, you get a client ID and a client secret, which are used for authentication.
The application must request an AAD access token. This can be done through an OAuth 2.0 authorization flow. A common example is the flow of client credentials: the application sends a POST request to the AAD token endpoint with the client ID, client secret, and desired scope (for example, https://{tenant}.sharepoint.com/.default).
If the credentials are correct, AAD returns a JSON Web Token (JWT) access token. The application will then use this access token to make authenticated calls to the SharePoint REST API. The token is sent in the HTTP request header as
Authorization: Bearer {access_token}
Authentication for the Microsoft Graph API follows a similar (if not in some ways identical) process, using OAuth 2.0, but with some specific details for accessing Microsoft 365 services.
Where SharePoint REST API requires tokens directly from the Azure Active Directory endpoint with specifications for the SharePoint tenant, Graph, while using the Azure Active Directory endpoint, specifies the scope of Graph to obtain a token (example: https://graph.microsoft.com/.default).
The scopes are wider than those of the SharePoint REST API and can cover different resources within Microsoft 365. This therefore allows access to a variety of services, not only to SharePoint, but also to Outlook, OneDrive, Teams and other Microsoft 365 applications.
Authorizations are therefore much more centralized and cover a wider range of services, and scopes may include permissions such as User.Read, Files.readwrite.all, Mail.Read, in addition to SharePoint-specific permissions.
This concludes our overview of the APIs currently available for SharePoint, but we would still like to make a small final clarification on what will be the next developments regarding the topic.
With Microsoft continuing to focus its development and updating efforts on Microsoft Graph, it's clear that this API represents the future of data integration and management for the entire Microsoft 365 ecosystem, at the expense of the older (albeit more specialized) SharePoint REST API.
By exploiting the potential of a single programming interface to access all the necessary resources and services, developers will be able to significantly reduce the complexity of managing multiple endpoints and improve the consistency of the applications developed, while facilitating the implementation of solutions based on artificial intelligence and machine learning, fields in which Microsoft has now decided to invest significantly.
Developers and companies are therefore encouraged to start the transition to the Microsoft Graph API, in order to take full advantage of the new opportunities offered by the close integration between the software of the Microsoft 365 environment and ensure that their applications keep up with the technological evolution of contemporary digital workplaces.
SharePoint APIs are a set of tools and protocols that allow developers to interact with SharePoint, enabling them to integrate, customize, and extend SharePoint functionalities within their applications.
There are several types of SharePoint APIs, including REST APIs, CSOM (Client-Side Object Model), JSOM (JavaScript Object Model), and SOAP services. These APIs provide various methods for accessing SharePoint data and services.
SharePoint REST APIs allow you to perform CRUD (Create, Read, Update, Delete) operations on SharePoint data using standard HTTP methods. You can interact with SharePoint lists, libraries, users, and other resources via RESTful endpoints.
The Client-Side Object Model (CSOM) is a set of libraries that allows developers to interact with SharePoint from client-side applications. It provides a way to access SharePoint data and perform operations using .NET, JavaScript, and other client technologies.
SharePoint APIs, particularly JSOM (JavaScript Object Model), provide extensive support for integrating SharePoint with JavaScript. This allows developers to create dynamic, client-side web applications that interact with SharePoint without the need for server-side code.
Yes, SharePoint APIs support various authentication methods, including OAuth, Azure AD, and classic SharePoint authentication. These methods allow secure access to SharePoint resources through the APIs.
SOAP services are legacy APIs in SharePoint that provide web service-based access to SharePoint functionality. While less commonly used in modern applications, they are still supported and can be used for specific legacy integration needs.
SharePoint APIs can be leveraged to create and manage workflows programmatically. Through REST APIs and CSOM, developers can automate business processes, manage tasks, and integrate with other systems.
While SharePoint APIs strive to maintain backward compatibility, there can be differences between versions. Developers need to be aware of version-specific features and changes when working with different SharePoint environments.
When using SharePoint APIs, it's essential to implement proper error handling. APIs typically return HTTP status codes and error messages, which can be used to identify and troubleshoot issues in your application.
Security is critical when using SharePoint APIs. Developers should ensure that data access is properly authenticated and authorized, use HTTPS for secure communication, and follow best practices for API security and data protection.
Yes, SharePoint APIs can be integrated with Power Automate (formerly Microsoft Flow) to create automated workflows. This allows for powerful automation capabilities within SharePoint, leveraging API interactions.
SharePoint APIs provide the necessary endpoints and data structures to integrate with external applications. Developers can use REST APIs or other available interfaces to connect SharePoint with third-party systems, enabling seamless data exchange and process automation.
The Modern Work team effectively and swiftly addresses IT needs, primarily focusing on software development. The technical staff is well-trained in implementing software projects using Microsoft technology stacks and is skilled in managing both agile and long-term projects.
