SharePoint’s user interface handles most everyday tasks—uploading documents, managing lists, navigating sites. But when you need to automate operations at scale, integrate SharePoint with other systems, or build custom applications, you need the SharePoint API.
APIs (Application Programming Interfaces) let code interact with SharePoint programmatically. Instead of clicking through the interface to create a hundred list items, a script can create them in seconds. Instead of manually copying data between systems, an integration can synchronize information automatically. Instead of building features within SharePoint’s constraints, custom applications can provide tailored experiences.
This guide covers how SharePoint APIs work, when to use different approaches, and practical examples to get you started.
SharePoint API Options
SharePoint offers multiple API approaches for different scenarios:
Microsoft Graph API is Microsoft’s unified API for accessing data across Microsoft 365, including SharePoint. It’s the recommended approach for new development and provides consistent authentication, modern REST conventions, and access to SharePoint alongside other Microsoft 365 services.
SharePoint REST API provides direct access to SharePoint resources through HTTP requests. It predates Microsoft Graph and offers some SharePoint-specific operations not yet available in Graph. Many existing integrations use SharePoint REST.
CSOM (Client-Side Object Model) is a .NET library for SharePoint operations, available for both managed code and JavaScript. It’s older than REST approaches but still used in some scenarios, particularly in SharePoint Framework (SPFx) development.
SharePoint Framework (SPFx) isn’t an API itself but a development model for building SharePoint customizations that use these APIs internally. SPFx web parts and extensions interact with SharePoint through Graph and REST APIs.
For most new projects, start with Microsoft Graph. Fall back to SharePoint REST for operations Graph doesn’t support. Use CSOM when working with existing codebases or specific scenarios where it’s advantageous.
Microsoft Graph for SharePoint
Microsoft Graph provides access to SharePoint sites, lists, libraries, and documents through a unified endpoint.
Base URL: https://graph.microsoft.com/v1.0/
Common SharePoint operations via Graph:
Get a site:
GET /sites/{site-id}
GET /sites/{hostname}:/{site-path}
List document libraries:
GET /sites/{site-id}/drives
Get files in a library:
GET /sites/{site-id}/drives/{drive-id}/root/children
Create a list item:
POST /sites/{site-id}/lists/{list-id}/items
Content-Type: application/json
{
“fields”: {
“Title”: “New Item”,
“Status”: “Active”
}
}
Upload a file:
PUT /sites/{site-id}/drives/{drive-id}/root:/{filename}:/content
Content-Type: application/octet-stream
[file contents]
Graph uses OAuth 2.0 authentication through Azure AD (Microsoft Entra ID). Applications register in Azure AD and request appropriate permissions—either delegated permissions (acting on behalf of a user) or application permissions (acting as the application itself).
SharePoint REST API
The SharePoint REST API provides direct access to SharePoint objects through the _api endpoint on SharePoint sites.
Base URL: https://{tenant}.sharepoint.com/sites/{site}/_api/
Common operations:
Get site information:
GET /_api/web
Get all lists:
GET /_api/web/lists
Get items from a list:
GET /_api/web/lists/getbytitle(‘Tasks’)/items
Create a list item:
POST /_api/web/lists/getbytitle(‘Tasks’)/items
Content-Type: application/json;odata=verbose
X-RequestDigest: {form digest value}
{
“__metadata”: { “type”: “SP.Data.TasksListItem” },
“Title”: “New Task”
}
Update a list item:
POST /_api/web/lists/getbytitle(‘Tasks’)/items({item-id})
Content-Type: application/json;odata=verbose
X-RequestDigest: {form digest value}
IF-MATCH: *
X-HTTP-Method: MERGE
{
“__metadata”: { “type”: “SP.Data.TasksListItem” },
“Status”: “Completed”
}
Delete a list item:
POST /_api/web/lists/getbytitle(‘Tasks’)/items({item-id})
X-RequestDigest: {form digest value}
IF-MATCH: *
X-HTTP-Method: DELETE
SharePoint REST requires a request digest token for write operations. In browser-based code, this is typically retrieved from the page or through a specific endpoint. Server-side code uses OAuth tokens similar to Graph.
Authentication Methods
Accessing SharePoint APIs requires authentication. The approach depends on your scenario:
Delegated authentication means the application acts on behalf of a signed-in user. The user authenticates, and the application receives a token with permissions based on what that user can access. Use this for applications where users are present.
Application authentication means the application authenticates as itself, not on behalf of a user. This enables automation scenarios—scheduled jobs, background processes, integrations—where no user is interactively present. Application permissions must be explicitly granted by an administrator.
Azure AD app registration is required for both approaches. Register your application in Azure AD, configure required permissions (Microsoft Graph permissions for Graph API, SharePoint permissions for REST API), and implement the OAuth flow appropriate to your scenario.
Certificate-based authentication is recommended for application permissions, providing stronger security than client secrets.
For SharePoint REST API in browser-based code running on SharePoint pages (like SPFx), authentication is handled automatically through the user’s session.
Practical Code Examples
JavaScript: Reading List Items with Graph
async function getListItems(siteId, listId, accessToken) {
const response = await fetch(
`https://graph.microsoft.com/v1.0/sites/${siteId}/lists/${listId}/items?expand=fields`,
{
headers: {
‘Authorization’: `Bearer ${accessToken}`,
‘Content-Type’: ‘application/json’
}
}
);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
const data = await response.json();
return data.value;
}
JavaScript: Creating a List Item with SharePoint REST
async function createListItem(siteUrl, listTitle, itemData, digestValue) {
const response = await fetch(
`${siteUrl}/_api/web/lists/getbytitle(‘${listTitle}’)/items`,
{
method: ‘POST’,
headers: {
‘Accept’: ‘application/json;odata=verbose’,
‘Content-Type’: ‘application/json;odata=verbose’,
‘X-RequestDigest’: digestValue
},
body: JSON.stringify({
‘__metadata’: { ‘type’: `SP.Data.${listTitle}ListItem` },
…itemData
})
}
);
if (!response.ok) {
throw new Error(`API error: ${response.status}`);
}
return await response.json();
}
PowerShell: Bulk Operations with PnP PowerShell
PnP PowerShell is a community library that simplifies SharePoint operations:
# Connect to SharePoint
Connect-PnPOnline -Url “https://contoso.sharepoint.com/sites/projects” -Interactive
# Get all items from a list
$items = Get-PnPListItem -List “Projects”
# Create a new list item
Add-PnPListItem -List “Projects” -Values @{
“Title” = “New Project”
“Status” = “Planning”
“StartDate” = Get-Date
}
# Update an item
Set-PnPListItem -List “Projects” -Identity 42 -Values @{
“Status” = “In Progress”
}
# Bulk upload files
$files = Get-ChildItem “C:\Documents\*.pdf”
foreach ($file in $files) {
Add-PnPFile -Path $file.FullName -Folder “Shared Documents”
}
C#: Using the Graph SDK
using Microsoft.Graph;
using Azure.Identity;
// Create Graph client with app-only authentication
var credential = new ClientSecretCredential(
tenantId, clientId, clientSecret);
var graphClient = new GraphServiceClient(credential);
// Get list items
var items = await graphClient
.Sites[siteId]
.Lists[listId]
.Items
.Request()
.Expand(“fields”)
.GetAsync();
// Create a list item
var newItem = new ListItem
{
Fields = new FieldValueSet
{
AdditionalData = new Dictionary<string, object>
{
{ “Title”, “New Item” },
{ “Status”, “Active” }
}
}
};
await graphClient
.Sites[siteId]
.Lists[listId]
.Items
.Request()
.AddAsync(newItem);
Common API Use Cases
Data migration and bulk operations. Moving large amounts of content, creating many items, or updating records in bulk. APIs enable operations that would be impractical through the UI.
System integrations. Synchronizing SharePoint with CRM, ERP, HR systems, or custom databases. When data changes in one system, APIs update the other.
Custom applications. Building applications that use SharePoint as a data backend but provide custom user interfaces tailored to specific workflows.
Automated workflows. While Power Automate handles many workflow scenarios, complex or high-volume automation sometimes requires direct API interaction.
Reporting and analytics. Extracting data from SharePoint for analysis, reporting, or dashboards beyond what built-in reporting provides.
Content management automation. Automatically organizing, tagging, or moving content based on rules or external triggers.
For organizations managing complex project documentation, APIs enable custom solutions that support project information management beyond out-of-box SharePoint capabilities.
Rate Limits and Best Practices
SharePoint and Microsoft Graph implement throttling to ensure service stability. Exceeding limits results in HTTP 429 (Too Many Requests) responses.
Handle throttling gracefully:
- Implement retry logic with exponential backoff
- Respect Retry-After headers when present
- Spread requests over time rather than bursting
- Use batch requests where possible
Batch requests combine multiple operations into single HTTP calls, reducing round trips and improving throughput:
POST https://graph.microsoft.com/v1.0/$batch
Content-Type: application/json
{
“requests”: [
{ “id”: “1”, “method”: “GET”, “url”: “/sites/{site-id}/lists” },
{ “id”: “2”, “method”: “GET”, “url”: “/sites/{site-id}/drives” }
]
}
Additional best practices:
- Request only the fields you need using $select
- Use $filter to retrieve only matching items rather than filtering client-side
- Implement proper error handling for all API calls
- Log API operations for debugging and auditing
- Store authentication tokens securely; never expose them in client-side code
- Use application permissions sparingly; prefer delegated permissions when users are present
Choosing the Right API Approach
Use Microsoft Graph when:
- Building new applications or integrations
- You need consistent access to multiple Microsoft 365 services
- Graph supports your required operations
- You want the most modern and maintained API
Use SharePoint REST when:
- You need SharePoint-specific operations not in Graph
- Working with existing code using REST
- You need operations like managing content types, workflows, or site features
- Building SPFx solutions that need direct SharePoint access
Use PnP PowerShell when:
- Performing administrative tasks or one-time operations
- Bulk content management or migration
- Scripting repetitive SharePoint tasks
- You prefer PowerShell over writing custom code
Use CSOM when:
- Maintaining existing solutions built on CSOM
- Specific operations are easier in CSOM
- Building certain types of SPFx components
Getting Started
- Learn the basics. Microsoft’s documentation provides comprehensive API references. Start with Microsoft Graph documentation for SharePoint.
- Set up a development environment. Create a test site collection. Register an Azure AD application with appropriate permissions.
- Use Graph Explorer. Microsoft’s Graph Explorer (https://developer.microsoft.com/graph/graph-explorer) lets you test API calls interactively before writing code.
- Start simple. Begin with read operations—listing sites, retrieving list items. Progress to write operations once comfortable with authentication and request structure.
- Leverage libraries. SDKs for various languages simplify authentication and API interaction. Use them rather than building everything from scratch.
Need help building SharePoint integrations or custom applications? Reach out to discuss your development requirements.