How to Build a SharePoint REST API URL

Want to integrate SharePoint with other systems, or maybe you're looking to display important SharePoint data on your SharePoint sites? Understanding the SharePoint REST API is essential to accomplish all these. Let's dive into what makes this so powerful, how to start building SharePoint REST API URLs, and how you can leverage it in your projects to access SharePoint data efficiently.

TABLE OF CONTENTS

• What is the SharePoint REST API?
• Types of REST API Queries
• Understanding GET Queries
• Building SharePoint REST API URLs
  • Step 1: Start with Your Site URL
  • Step 2: Add the REST API Entry Point
  • Step 3: Choose Your Context
  • Step 4: Navigate to Your Resource
  • Step 5: Add Query Parameters
  • Step 6: Combine Multiple Parameters
  • Step 7: Use the SharePoint REST API URL in your SharePoint sites
• Ready to start RESTing?
• Frequently Asked Questions
  • What's the difference between the SharePoint REST API and Microsoft Graph API?
  • Do I need special permissions to use the REST API?
  • Can I use the REST API with SharePoint On-Premises?
  • What's the maximum number of items I can retrieve in a single request?
  • How do I handle large result sets?
  • Can I use REST API calls in SharePoint Framework (SPFx) solutions?

What is the SharePoint REST API?

The SharePoint REST API is a web service that allows developers to interact with Microsoft SharePoint data remotely using standard HTTP requests. It's like a universal translator that lets any client applications communicate with SharePoint in a language they all understand.

Built on the standard Open Data Protocol (OData), the REST interface follows Representational State Transfer (REST) principles, making it intuitive and straightforward to use. You can perform all the essential CRUD operations (Create, Read, Update, Delete) on SharePoint entities like sites, SharePoint lists, SharePoint libraries, items, and documents. This opens up SharePoint to a much broader ecosystem of tools and platforms.

Types of REST API Queries

To start using REST capabilities, you must construct a RESTful HTTP request. The SharePoint REST API supports several HTTP methods, each designed for specific operations:

• GET - Retrieves data from SharePoint (reading SharePoint resources)
• POST - Creates new items or executes post commands
• PUT - Updates existing items by replacing all properties
• DELETE - Removes items (often sending them to the Recycle Bin) using the HTTP DELETE command

While all these methods have their place, GET requests are the workhorses of the REST API. They're used constantly for retrieving information, and they're the safest type of request since they don't modify any data. Let's focus on GET queries since they're typically your starting point when working with the API.

Understanding GET Queries

GET requests are read-only operations that retrieve data from SharePoint. They're perfect for displaying information, building reports, or pulling data into external applications. Executing a GET query is very simple. Just construct a SharePoint REST URL pointing to the resource you want, and the SharePoint server sends back the data.

Every SharePoint REST API URL follows this anatomy:

https://{domain}/{site}/_api/{context}/{resource-path}?{query-parameters}

Let's examine each component:

• Domain: This is your SharePoint domain. You can find this in the address bar of your SharePoint sites. For example, contoso.sharepoint.com.
• Site: This is your site path. For example, /sites/marketing.
• _api: This is the fixed entry point to the REST service.
• Context: Here, you need to add any of the following:
  • site - if you want to retrieve data from your site collection
  • web - if you want to retrieve data from your current site
• Resource-path: This is where you add which specific resources you want to retrieve. Here are a few URL paths to get you started:
  • title - get site titles
  • lists - get all lists
  • getbytitle('List Name') - get a specific list by title
  • getbytitle('List Name')/items - get all items from a list
  • getbytitle('List Name')/items(5) - get a specific item by ID
  • getbytitle('List Name')/fields - access list properties
  • currentuser - get current user information
  • siteusers - get site users
  • folders - get all folders
  • GetFolderByServerRelativeUrl('Document Library Name/Folder Name')/Files - get all files from a specific folder inside a Document Library
• Query-parameters: These let you refine exactly what data you get back. You can use the following OData query operators:
  • $select - allows you to choose specific fields to return.
  • $filter - allows you to retrieve only items that match specific criteria.
  • $orderby - allows you to sort results by one or more fields.
  • $top - allows you to limit the number of results
  • $skip or $skiptoken - allows you to implement paging
  • $expand - allows you to include related data (like lookup fields) operators for filtering, selecting, and sorting

NOTEFor more information about these query parameters, check out ShortPoint REST API: Selecting, Filtering, Sorting Results in a SharePoint List

Building SharePoint REST API URLs

Creating effective SharePoint REST API URLs is the foundation of working with SharePoint data and performing CRUD operations efficiently. Let's break down the URL construction process step by step. For this guide, we want to retrieve all the files from a specific folder in a SharePoint Document Library:

Step 1: Start with Your Site URL

Begin by identifying your SharePoint site URL. You can typically find this in the address bar of your SharePoint sites:

https://contoso.sharepoint.com/sites/marketing

https://contoso.sharepoint.com/sites/marketing/_api/

https://contoso.sharepoint.com/sites/marketing/_api/web

https://contoso.sharepoint.com/sites/marketing/_api/web/GetFolderByServerRelativeUrl('PDF Guides/Guides')/Files

https://contoso.sharepoint.com/sites/marketing/_api/web/GetFolderByServerRelativeUrl('PDF Guides/Guides')/Files?
$orderby=Name asc

https://contoso.sharepoint.com/sites/marketing/_api/web/GetFolderByServerRelativeUrl('PDF Guides/Guides')/Files?
$orderby=Name asc&
$top=5