How to get started with the SharePoint REST API

Are you tired of writing many lines of code to perform CRUD (Create, Read. Update, Delete) operations? Let’s take a simple case of trying to read a SharePoint List and add items to it. Normally, you would have to write two functions using CSOM/JSOM/SSOM, such as:

1. ReadList()
2. AddListItem()

With the advent of REST in SharePoint, you can now focus your efforts on functionality rather than code/language. All you have to do is to construct the URL based on your needs and reuse the REST CRUD code.

The SharePoint team has done a lot of coding to make the functionality common across a URL.

All you need to do is, append the SharePoint site URL with REST Url.

Let’s see how.

Construction of REST Url

The REST Url begins with /_api/

After the API, you specify the Object. Example web, site. For nested objects /web/lists

Let’s begin with a simple Url that reads the Site Url.

First, you get the Site Collection Url and then append that with the Rest Url

Example:

• https://abc.sharepoint.com/sites/dev/_api/site/Url

If you open the above Url, you would see output like below:

• <d:Url>https://abc.sharepoint.com</d:Url>

The results can be accessed by data.d or data.d.results for multiple items

If you are new to REST, here is a quick explanation of REST basics. Teh REST technology allows developers to write functions using any technology of their choice and publish that as a URL which does the following tasks for a resource/object:

• GET- Read the object and returns the results mostly in JSON/XML format
• POST- Get the data details and Add Items
• PUT – Update the Object
• DELETE – Delete the Object

How to use PowerShell with SharePoint to code against the REST API

Let’s use PowerShell to get connected to SharePoint URL and do various Read operations. The cool thing is there are only one PowerShell code and the URL alone changes. In regular CSOM coding, you need to remember the Class and the methods to get your job done. In REST, the code remains the same and the URL alone changes.

You can download the code from here.

Here is a quick summary of the PowerShell code to do the CRUD operations.

1. Get connected to SharePoint using SharePoint credentials
2. Add the necessary headers to $headers based on CRUD operation
   1. GET- “Accept”, “application/json;odata=verbose”
   2. POST- “X-RequestDigest”, $formDigest from /_api/contextinfo
   3. PUT- “X-HTTP-Method”, “PUT” or “MERGE”
   4. PUT- “X-HTTP-Method”, “DELETE”
3. Invoke-RestMethod -Uri $fullUrl -Headers $headers -Method Post -WebSession $webSession -ContentType “application/json;odata=verbose”

Once, you run the above code, you can start using Read-SPObject,Create-SPObject,Update-SPObject on various SharePoint objects like Site, Lists,Files and many more based on your needs.

Add List Items using REST

Let’s start with our original need to read a SharePoint List and add Items to a SharePoint list say PSRestList.

$targetSite="https://xxx.sharepoint.com/sites/dev"
$User="admin@xxx.onmicrosoft.com"
$restUrl="/_api/web/lists/getbytitle('PSRestList')"
$listsPSRest=Read-SPObject -targetSite $targetSite -User $User -restUrl

Below are the details needed to add a item to a SharePoint list. Note that the data part contains the List Name, List Columns like Title.

#Add List Item
$listName="PSRestList"
$data=@"
{ '__metadata': { 'type': 'SP.Data.$($listName)ListItem' }, 'Title': 'OneTwoThree','CurrencyThangu':'2500' }
"@
$restUrl="/_api/web/lists/GetByTitle('"+$listName+"')/items"
$listItemNew=Create-SPObject -targetSite $targetSite -User $User -restUrl $restUrl -data $data

Summary

As a quick summary, you learnt the following:

1. Basics of REST and its benefits
2. Construction of SharePoint REST Url
3. PowerShell code that Invokes the SharePoint URL
4. Adding a SharePoint List Item using the REST Url.

If you like to learn by watching videos, here is a sample REST demo.