Two APIs, One Platform
SharePoint exposes two overlapping but distinct APIs. The classic SharePoint REST API, rooted at {siteUrl}/_api/, is scoped to a single site and predates most of Microsoft 365. Microsoft Graph, rooted at https://graph.microsoft.com, is the modern, unified API spanning SharePoint, Teams, OneDrive, and Outlook under one consistent authentication and permission model. Microsoft has stated Graph is the strategic direction, but REST remains fully supported for SharePoint-specific operations Graph doesn't yet cover.
Cricket analogy: Choosing between the SharePoint REST API and Microsoft Graph is like a fan choosing between a stadium's local scoreboard feed, scoped just to that ground, and the ICC's unified global stats feed covering every ground worldwide.
Calling the SharePoint REST API
A typical REST call, such as _api/web/lists/getbytitle('Requests')/items, reads or writes data for a single site's list. Requests are always scoped to the site they're called against — there is no built-in way to query across multiple site collections in one REST call, which is one of the API's biggest practical limitations compared to Graph.
Cricket analogy: Calling _api/web/lists/getbytitle('Matches')/items is like walking up to a specific stadium's ticket office and asking directly for that ground's fixture list rather than a national database.
OData Query Options
Both APIs support OData query parameters to shape responses: $select trims returned fields, $filter narrows rows server-side, $expand pulls in related entities like a lookup or author field inline, and $top caps the number of results. Combining these reduces payload size and round trips compared to fetching every field of every item and filtering client-side.
Cricket analogy: Using $filter=Result eq 'Win' with $select=MatchDate,Opponent is like asking a scorer to hand you only the wins, and only the date and opponent columns, instead of the full scorecard.
// GET with OData query options
fetch(`${siteUrl}/_api/web/lists/getbytitle('Requests')/items` +
`?$select=Title,Status,Author/Title&$expand=Author&$filter=Status eq 'Open'&$top=25`, {
headers: { Accept: 'application/json;odata=nometadata' }
}).then(r => r.json());
// POST requires a fresh request digest
const digest = document.getElementById('__REQUESTDIGEST').value;
fetch(`${siteUrl}/_api/web/lists/getbytitle('Requests')/items`, {
method: 'POST',
headers: {
Accept: 'application/json;odata=nometadata',
'Content-Type': 'application/json;odata=nometadata',
'X-RequestDigest': digest
},
body: JSON.stringify({ Title: 'New request', Status: 'Open' })
});Microsoft Graph and SharePoint Sites
Graph represents a SharePoint document library as a 'drive' and its files and folders as 'driveItems', the same object model used for OneDrive. A call like GET /sites/{site-id}/drive/root/children lists the root of a library, and the same client code that reads a OneDrive folder can, with minor changes, read a SharePoint library, since both resolve to the same underlying resource type.
Cricket analogy: Fetching a SharePoint document library through Graph's /sites/{id}/drive/root/children endpoint is like the ICC pulling ground-keeping records through the same unified reporting system it uses for every stadium in the world.
Microsoft Graph enforces application- and delegated-permission scopes (e.g., Sites.Read.All, Files.ReadWrite.All) that must be consented to in Azure AD, and calls are subject to service-specific throttling limits; when a request is throttled, Graph returns a 429 with a Retry-After header that well-behaved clients should honor with exponential backoff rather than immediate retry.
The X-RequestDigest value used to authorize SharePoint REST POST/PATCH/DELETE calls typically expires after about 30 minutes (the tenant's form digest timeout) — long-running single-page sessions must refresh it via a call to _api/contextinfo before the next write, otherwise the request fails with a 403 Invalid form digest error even though the user's session itself is still valid.
- SharePoint exposes both a classic REST API (_api/web/...) and the modern Microsoft Graph API (graph.microsoft.com).
- REST endpoints are scoped to a single site and use OData query options ($select, $filter, $expand, $top) to shape responses.
- Write operations against the REST API require a valid X-RequestDigest header, obtained from the page or _api/contextinfo.
- Graph API represents SharePoint document libraries as 'drives' and files/folders as 'driveItems', unified with OneDrive.
- Graph requires explicit permission scopes consented in Azure AD and applies its own throttling with 429/Retry-After.
- Choose REST for legacy, site-scoped scripting; choose Graph for modern, cross-service, tenant-wide integrations.
- Both APIs return JSON and can be called from SPFx components, Power Automate, or external applications with proper auth.
Practice what you learned
1. What HTTP header is required for write operations (POST/PATCH/DELETE) against the SharePoint REST API?
2. In Microsoft Graph, what object represents a file or folder inside a SharePoint document library?
3. Which OData query option limits the fields returned in a REST or Graph response?
4. What HTTP status code indicates a Graph API request was throttled?
5. Roughly how long does a SharePoint REST X-RequestDigest remain valid before it must be refreshed?
Was this page helpful?
You May Also Like
The SharePoint Framework (SPFx)
SPFx is Microsoft's modern, open-source development model for building client-side web parts and extensions that run natively in SharePoint Online.
Workflows with Power Automate
Power Automate replaces SharePoint Designer workflows with cloud-based flows that automate approvals, notifications, and data processing triggered by SharePoint events.
Power Platform Integration
Power Apps, Power Automate, and Power BI connect to SharePoint lists and libraries as a shared low-code data source and business logic layer.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics