SharePoint REST API Builder

The SharePoint REST API, and when not to use it

The SharePoint REST API exposes lists, libraries, files, users and site settings over plain HTTP, so anything that can make a request can use it. It remains the right tool for site-scoped work: list and library operations, file upload and check-in, permissions, and most of what sits under _api/web. For cross-service work — users, groups, Teams, mail, calendar — Microsoft Graph is the better endpoint, and Graph now covers a large share of SharePoint content operations too. Prefer Graph for new work unless you need surface only the SharePoint API exposes.

Address lists by ID, not by title

getByTitle('Documents') is the form everyone writes and the form that breaks: renaming a list changes its title and every hard-coded URL with it, and a localised tenant may not have the title you expect in the first place. lists(guid'...')survives renames. Note also that a list's URL and its title are independent — neither follows the other after a rename.

Expanding lookups requires selecting through them

$expandon its own does very little. To get an author's display name you need both halves: $select=Title,Author/Title&$expand=Author. Selecting only Author returns a metadata stub, and expanding without selecting the sub-field returns the same. Lookup columns follow the same pattern, and the raw ID is available with no expand at all as <FieldName>Id, which is cheaper when the ID is all you need.

Internal names, not display names

Every $select and $filter takes the column's internal name. Internal names are fixed at creation and never change, so a column created as “Due Date” and later renamed to “Deadline” is still Due_x0020_Date in every query. Spaces become _x0020_ and other punctuation gets similar escapes. A query that returns rows but ignores your filter is almost always a display name SharePoint could not resolve.

The 5,000 item threshold applies here too

Filtering a list of more than 5,000 items on a column that is not indexed throws rather than returning a partial result, and it throws however few items match. Indexing the filtered column fixes it. $top caps at 5,000 per request and larger result sets page through @odata.nextLink (or __nexton the older verbose format) — follow the link rather than incrementing a skip counter.

Writes need more than a POST

Reads are simple; writes are where the API gets particular. From a page context a write needs the form digest in an X-RequestDigest header. Updates are a POST carrying X-HTTP-Method: MERGE and an IF-MATCH header — *to overwrite unconditionally, or the item's ETag for optimistic concurrency. Deletes use X-HTTP-Method: DELETE. In SPFx, SPHttpClient attaches the digest and the right headers for you, which is the main reason to prefer it over raw fetchinside a web part.

Ask for less metadata

The default response format is verbose and can be several times the size of the data you wanted. Sending Accept: application/json;odata=nometadata strips the type annotations and flattens the payload, removing the d.results nesting that older examples index through. Use odata=minimalmetadata when you still need the ETag for concurrent updates.

Authentication

Inside an SPFx web part the context handles this and you should not be managing tokens yourself. Outside it, register an application in Microsoft Entra IDand grant the narrowest scope that works — Sites.Selected, which grants access to named sites, rather than the tenant-wide reach of Sites.Read.All or Sites.ReadWrite.All. Tenant-wide application permissions are what turn a leaked secret into a tenant-wide incident.