SharePoint REST and Graph API

Analogy categoryAnalogies

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.

javascript

// 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.