SharePoint REST API: Explained With Examples

The SharePoint REST API has quickly become a go-to method for connecting external applications and services to SharePoint sites. It gives organizations the power to maximize their investment in the SharePoint platform.

The SharePoint REST API is a flexible and efficient method for interacting with SharePoint data remotely, providing a powerful alternative to traditional client APIs. By leveraging the SharePoint REST API, developers can efficiently integrate SharePoint functionality into their own applications.

If you’re a developer looking to integrate SharePoint into your applications, this comprehensive guide will give you all the information and steps that you will need to make your integration both effective and successful.

Now let’s start at the beginning with some basics!

Understanding the Basics of SharePoint REST API

What is REST?

REST, which stands for Representational State Transfer, is an architectural style that guides the design and development of networked systems. It’s a lightweight and flexible way to interact with SharePoint remotely using any technology that supports the REST protocol.

REST emphasizes a stateless client-server communication model, where clients send requests to servers to perform actions on resources. These requests are typically in the form of HTTP methods like GET, POST, PUT, PATCH, and DELETE, which align with different operations on the resources.

The REST architecture focuses on the notion of resources, which are identified by unique URLs and is based on the standard Open Data Protocol (OData) and allows developers to perform basic create, read, update, and delete (CRUD) operations through a RESTful HTTP request.

In the context of SharePoint, resources can be items in a SharePoint list, documents in a SharePoint library, or even the SharePoint site itself. By interacting with these resources using HTTP requests, clients can retrieve information, make modifications, and perform other actions.

Key Concepts of the SharePoint REST API

1. Endpoints: SharePoint resources, such as lists, libraries, or sites, are exposed through specific URLs called endpoints. These endpoints represent the entry points to interact with SharePoint resources using the REST API.
2. HTTP requests and methods: To work with the SharePoint REST API, you need to create and send HTTP requests to the appropriate SharePoint API endpoints. These HTTP requests utilize different methods to perform basic operations:
   • GET: Retrieve information from the server
   • POST: Create a new item on the server
   • PUT: Update an existing item on the server
   • PATCH: Partially updates an existing item.
   • DELETE: Remove an item from the server
   For example, an HTTP GET request to this endpoint retrieves a list of items from a SharePoint site:https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')/items
3. Constructing requests and handling responses: To interact with the SharePoint REST API, developers need to construct HTTP requests with the necessary information, such as the target endpoint, headers, and sometimes request bodies.The requests are sent to the SharePoint server, which processes them and returns responses. These responses contain the requested data, confirmation of a successful operation, or error messages if any issues arise.
4. SharePoint client object models: The SharePoint REST API provides functionality that corresponds to various client object models, including:

• JavaScript (JSOM): Via JavaScript libraries, you can interact with SharePoint remotely.
• Silverlight (CSOM): Using .NET libraries, you can create Silverlight applications that work with SharePoint.
• Managed .NET (CSOM): Through C# or VB, you can build client applications that SharePoint is compatible with, using managed .NET code.
• Mobile (MCSOM): You can create Windows Phone apps that leverage SharePoint REST API with Microsoft’s Mobile Client Object Model.Each client object model allows you to interact with all the SharePoint entities, such as lists, SharePoint libraries, content types, and more.

5. SharePoint Online: In the context of SharePoint Online, the REST API plays a crucial role by allowing the integration of SharePoint content and features into various client and mobile applications. When you query SharePoint Online using the REST API, you get results from:
   • Content in SharePoint Online site collectionsContent in Microsoft 365 groups
   The SharePoint Search REST API enables you to add search functionality to your applications, providing a seamless and efficient way for SharePoint site users to access SharePoint content from different platforms and devices.

Understanding these fundamental concepts will provide a solid foundation for working with the SharePoint REST API. Now let’s explore the practical aspects of integrating with SharePoint using the REST API in the next section!

Getting Started with SharePoint REST API Integration

In this section, we’ll delve into the process of integrating SharePoint’s REST API into your applications. We’ll go over the authentication and authorization process and then how to set up your development environment.

Authentication and Authorization Process

When integrating with SharePoint using the REST API, it’s crucial to understand the authentication and authorization process. SharePoint employs a variety of authentication methods to ensure secure access to its resources.

Here are some key points on authentication to consider:

1. Different authentication options: SharePoint supports multiple authentication options, including OAuth, app-only authentication, and more. OAuth is commonly used and involves obtaining an access token that represents the authenticated user or application.

2. Obtaining access tokens for API requests: To make API requests, you need to obtain an access token. The token is acquired through an authentication process, where the requesting applicant presents valid credentials and receives a token in return. This token is then included in subsequent API requests to prove the authenticity of the requester.

Setting Up the Development Environment

To start integrating with the SharePoint REST API, you’ll need to set up your development environment. Here are some points to consider.

1. Required tools and libraries: Depending on your programming language or platform, there are various tools and libraries available to facilitate SharePoint REST API integration. These may include SDKs (Software Development Kits), code libraries, or development frameworks specific to your chosen programming language.

2. Establishing connections to SharePoint sites: In order to interact with SharePoint using the REST API, you need to establish a connection to the SharePoint site or site collection you want to work with. This typically involves providing the site URL of the SharePoint site and the appropriate authentication credentials.

Once you have your development environment set up, you are ready to start leveraging the power of the SharePoint REST API to interact with SharePoint resources programmatically.

Now that you have a solid understanding of the basics and have set up your development environment, it’s time to explore the various operations that can be performed using the SharePoint REST API.

Performing Operations with SharePoint REST API

In this section, we’ll delve into the various operations that can be performed to retrieve data, create and update resources, delete items, and work with metadata.

Understanding these operations and their implementation through the SharePoint REST API will empower you to efficiently interact with SharePoint, automate tasks, and streamline your workflows.

1. Fetching Data from SharePoint

Retrieving data from SharePoint through REST API is a valuable technique for developers when working with a particular SharePoint group such as a group of files, documents, properties, metadata, and more. The REST interface allows developers to perform various CRUD operations with ease using HTTP requests.

i. Files and Documents

To interact with files and documents using the SharePoint REST API, you can use methods like GET, POST, PUT, MERGE, and DELETE. Each method represents a specific action: retrieving, creating, updating, merging, and deleting files or documents, respectively.

For example, to fetch a list of items in a specific SharePoint document library, you can use the following HTTP request:

GET https://<site>.sharepoint.com/_api/web/lists/getbytitle('Documents')/items

You can also fetch files within a specific folder using:

GET https://<site>.sharepoint.com/_api/web/getfolderbyserverrelativeurl('<folder path>')/files

ii. Properties and Metadata

SharePoint entities, such as files, documents, and folders, have properties and metadata associated with them. The SharePoint REST API enables developers to fetch and manage this information.

To retrieve properties of a file, use the following request:

GET https://<site>.sharepoint.com/_api/web/getfilebyserverrelativeurl('<file path>')/ListItemAllFields

Updating metadata of a file requires the MERGE method along with additional header information:

MERGE https://<site>.sharepoint.com/_api/web/lists/getbytitle('Documents')/items(<item id>)
Headers:
    Content-Type: application/json;odata=verbose
    If-Match: *
    X-HTTP-Method: MERGE
Body:
    {
        "__metadata": {
            "type": "SP.Data.DocumentsItem"
        },
        "Title": "Updated Document Title"
    }

iii. Search and Query

Finding specific information or items in SharePoint is made easy using search and query capabilities of the REST API. These features allow developers to filter, order, and customize their search results based on various parameters.

One example is filtering items in a list by using the $filter query option:

GET https://<site>.sharepoint.com/_api/web/lists/getbytitle('List Name')/items?$filter=<filter condition>

Sorting search results can be done using the $orderby query option:

GET https://<site>.sharepoint.com/_api/web/lists/getbytitle('List Name')/items?$orderby=Column_Name

The SharePoint REST API also supports batch requests, allowing developers to combine multiple requests into a single call, improving performance:

POST https://<site>.sharepoint.com/_api/$batch

By leveraging the SharePoint REST API capabilities, you can efficiently fetch data from SharePoint, manage its properties and metadata, and perform accurate search queries while maintaining a smooth user experience.

2. Creating and Updating SharePoint Items

To create collections and items in SharePoint using the REST API, you can send HTTP POST commands with the appropriate JSON payloads.

For instance, to create a new list, construct a RESTful HTTP request using the JavaScript Object Notation (JSON) format, like so:

var listData = {
    '__metadata': { 'type': 'SP.List' },
    'Title': 'NewList',
    'Description': 'This is a new list.'
};

Then, make an HTTP POST request to the following URI:

/_api/Web/Lists

Similarly, to add an item to a list, send a POST request with the JSON payload representing the new item:

var itemData = {
    '__metadata': { 'type': 'SP.Data.ListNameListItem' },
    'Title': 'New Item'
};

The request should be sent to the following URI:

/_api/Web/Lists/GetByTitle('ListName')/Items

i. Updating and Modifying Existing Data

You can update data in SharePoint by using the PUT or MERGE HTTP requests. These methods are often combined with X-HTTP-Method in the header to avoid issues related to certain firewalls and proxies. With MERGE, you can update only the properties you want to modify, while the PUT request will update all properties of an item, even if they’re not included in the request.

For instance, to update an item’s title, use the following JSON payload:

var updatedData = {
    '__metadata': { 'type': 'SP.Data.ListNameListItem' },
    'Title': 'Updated title'
};

Then, construct an HTTP POST request to the item’s URI, and update the item using the MERGE method:

/_api/Web/Lists/GetByTitle('ListName')/Items(itemId)

ii. Deleting and Recycling SharePoint Objects

The SharePoint REST API provides options to delete and recycle objects, such as lists or items. To delete a SharePoint object, you can use the HTTP DELETE command. Alternatively, you can use the recycle operation to move an object to the recycle bin.

For example, to delete an item, send a POST request with an X-HTTP-Method of DELETE and the appropriate headers:

/_api/Web/Lists/GetByTitle('ListName')/Items(itemId)

To recycle an item, use the recycle endpoint, like so:

/_api/Web/Lists/GetByTitle('ListName')/Items(itemId)/recycle

iii. Managing List Items

SharePoint lists are an integral part of the SharePoint site architecture. Using REST APIs, you can manage list items easily by interacting with various endpoints related to lists and list items:

• Retrieve list information:GET https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')
• Create a new list item:POST https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')/items Include the JSON payload for the new item in the request body.
• Update an existing list item:PUT https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')/items(itemId) Include the updated JSON payload for the item in the request body.
• Delete a list item:DELETE https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')/items(itemId)

The SharePoint REST API simplifies the process of interacting with SharePoint entities, making it more convenient and efficient for developers to manage site collections, lists, and items programmatically.

Advanced Techniques and Integrations with SharePoint REST API

In this advanced section, we’ll delve deeper into the SharePoint REST API, exploring some of the more sophisticated techniques and integrations that can amplify the capabilities of your SharePoint applications.

1. Using the Graph API

Microsoft Graph API is a unified API endpoint for various cloud-based services, including SharePoint Online. With the Graph API, client applications can interact with SharePoint sites, lists, and libraries using RESTful web technologies.

The API follows the Open Data Protocol (OData) standard, allowing developers to perform CRUD operations on SharePoint entities using HTTP commands like GET, POST, PUT, and DELETE.

Here’s one of the SharePoint rest endpoint examples using Graph API. This is a REST endpoint URL for SharePoint Online through Graph API:

https://graph.microsoft.com/v1.0/sites/{site-id}/lists/{list-id}/items

This endpoint allows retrieving items from a specific list in a SharePoint Online site.

2. .NET Framework and Silverlight

Developers using the .NET Framework or Silverlight can also interact with SharePoint REST services. SharePoint provides client object models in these technologies, making it easy to work with SharePoint data in various .NET and Silverlight applications.

In the SharePoint REST service, REST endpoint URLs follow a specific pattern, enabling developers to perform operations on entities such as sites, lists, and fields.

Here’s an example of a REST endpoint URL structure for SharePoint:

http(s)://server/site/_api/web/lists

3. SocialFeedManager and SocialFollowingManager

The SharePoint REST API offers capabilities to leverage social features such as feeds and followings. The SocialFeedManager and SocialFollowingManager classes provide methods for managing social feeds and following content in SharePoint.

Using the SocialFeedManager, developers can create, read, update, and delete posts, replies, and likes in user feeds. The SocialFollowingManager class, on the other hand, enables managing and retrieving users and content being followed. Below are some examples of REST endpoint URLs for working with these classes:

• Retrieve a user’s feed:http(s)://server/site/_api/social.feed/my/feed
• Follow a site:http(s)://server/site/_api/social.following/follow

Final Thoughts

The SharePoint REST API provides a powerful means to interact with SharePoint programmatically, enabling developers to unlock the full potential of SharePoint for their organizations.

By following the guidelines, best practices, and examples outlined in this comprehensive guide, you are well-equipped to embark on your journey of integrating SharePoint with the REST API and building robust, customized solutions tailored to your unique needs. Embrace the power of the SharePoint REST API and unleash the full potential of SharePoint integration.

Take a course to learn how to integrate SharePoint with the Power Platform or watch this video to discover the possibilities:

Frequently Asked Questions

How do I authenticate with SharePoint REST API?

To authenticate with the SharePoint REST API, you have to first obtain an access token. This is typically achieved by registering an app in the Azure Active Directory and acquiring the token using the application’s credentials. Then, include the access token in the HTTP header of your REST calls, usually as a Bearer token.

How do I call SharePoint REST API from JavaScript?

To call SharePoint REST API from JavaScript, you can use the XMLHTTPRequest or the fetch API. These SharePoint APIs allow you to make HTTP requests like GET, POST, PUT, DELETE, and PATCH to interact with SharePoint REST endpoints. Make sure to construct properly formatted URLs for the endpoints and include the necessary headers for authentication and content type.

How can I interact with SharePoint lists using REST API?

You can interact with SharePoint lists using REST API by calling the appropriate endpoints for list and list item operations. To retrieve lists or list properties, use the api/web/lists endpoint. To create, read, update, or delete items from a list, use the api/web/lists/getbytitle(‘<listName>’)/items endpoint, replacing <listName> with your list’s name.

Are there any limitations or restrictions when using SharePoint REST API?

When using SharePoint REST API, some limitations and restrictions might apply. For instance, REST API requests are subject to the SharePoint threshold limit for data retrieval.

Additionally, certain operations may not be supported for specific scenarios or environments, like working with taxonomy fields, accessing on-premises SharePoint farms, or interacting with certain SharePoint add-ins and features.

Make sure to check the API documentation for specific functionality and limitations.