SharePoint Rest API [With Examples]

In this SharePoint tutorial, let us try to understand SharePoint rest api. We will see how to use rest api in SharePoint Online as well as how to use rest api in SharePoint 2013/2016/2019. To work with rest api in SharePoint, we need to clearly understand Rest API GET, POST, PUT, DELETE, and PATCH. I will also go through various SharePoint rest api examples in this tutorial. Here we will cover:

• What is SharePoint Rest API?
• Advantages of using Rest API in SharePoint
• Understanding SharePoint Rest API HTTP commands
  • GET
  • POST
  • PUT/MERGE
  • DELETE
• Various useful SharePoint REST endpoint examples
• SharePoint rest api crud operations
  • SharePoint rest api get all list items
  • SharePoint rest api insert list item
  • SharePoint rest api update list item
  • SharePoint rest api delete list item
• SharePoint rest api __metadata
• How to use SharePoint rest api in a browser
• Internet Explorer cannot display this feed
• Access SharePoint Rest API using Postman

What is SharePoint Rest API?

What is SharePoint Rest API? Rest API stands for Representational State Transfer and is based on standard Open Data Protocol (OData). By using Rest API, we can interact with SharePoint remotely by using any technology that supports Rest protocol. By using SharePoint rest api, we can do various operations like create, update, delete and display operations, like the SharePoint rest api CRUD operations.

By using Rest API, we can do CRUD operations from SharePoint Add-ins, solutions, and from client object model applications.

SharePoint Rest API is another form of client object model similar to JSOM, or CSOM.

Advantages of using Rest API in SharePoint

What are the advantages of using Rest API in SharePoint? One of the main advantages of SharePoint rest api is it allows you to work remotely with SharePoint sites using any technologies that support Rest protocols.

Another advantage of using Rest API is that you do not need to add any or refer to any SharePoint libraries or dlls to work with Rest API; you just need to make an HTTP rest endpoint (URL) for the SharePoint operations like insert, update, or delete.

SharePoint Rest API HTTP commands

Now let us try to understand SharePoint rest api HTTP commands. If you want to work with Rest API in SharePoint, the first thing we need to construct a Restful HTTP request by using the OData protocol standard.

If you want to do create, read, update, and delete operations using SharePoint Rest API, then we need to use the GET, POST, PUT, MERGE, DELETE, and PATCH HTTP methods.

GET

In rest API, we use the HTTP GET method if we want to read information from the SharePoint server or if we want to retrieve information from a SharePoint list if we want to read items from the SharePoint list. So mostly for the Read operations, we use the GET method.

POST

In SharePoint, if you want to create or update operations like creating a list or creating an item in a SharePoint Online list, then we use the Rest API POST operations. In Rest API POST operations, if any properties are not required, then these are set to their default values.

PUT/MERGE

In SharePoint Online, if you want to update an existing object, like an update item in a SharePoint list or update the SharePoint list title, then we can use the Rest API PUT and MERGE operations.

There is a little difference between HTTP PUT and MERGE in SharePoint rest api.

In the REST API MERGE HTTP method, setting properties is optional, and if any properties that you don’t explicitly set keep their current property.

For the PUT operations, it is mandatory to set up all the required properties while updating SharePoint objects. And for the optional properties, if you do not specify the values, then it will set to the default properties.

DELETE

As the name suggests, the HTTP DELETE method is used when we want to delete any SharePoint objects such as deleting SharePoint list, list items, documents, etc.

Now, I hope you got an idea of which HTTP commands, we should use while working with SharePoint rest api CRUD operations.

Various useful SharePoint REST endpoint examples

For doing any kind of operation in SharePoint using Rest API, the first thing we need to do is to create the rest endpoint. All the rest endpoint URL starts with:

https://SiteURL/Sites/SiteName/_api/

Example:

Below is an example of SharePoint Online.

https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/

For on-premises versions like SharePoint 2013, SharePoint 2016, or SharePoint 2019, the Rest api endpoint will be like the below:

http://bsahoo3:8787/sites/Training/_api/

Here are various SharePoint rest api endpoint examples; I have taken a SharePoint Online site as a reference, but the Rest API endpoints will be the same for SharePoint on-premises.

But while working with Rest API code, we can get the site URL by using the below JavaScript variable:

_spPageContextInfo.webAbsoluteUrl

You can check out more on How to use _spPageContextInfo JavaScript variable in SharePoint.

Operation	SharePoint Rest API endpoint
Get SharePoint site collection	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/site
Get specific SharePoint site or web	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web
Get SharePoint site title	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/title
Get all lists from a SharePoint site	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists
Get all items from a SharePoint list	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists/getbytitle(‘Trainings’)/items
Get SharePoint list title using Rest API	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists/getbytitle(‘Trainings’)?select=Title
Get all columns from a SharePoint list	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists/getbytitle(‘Trainings’)/Fields
Get SharePoint list by using a list GUIDs	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/Lists(List GUIDs)
Get SharePoint list item by item id	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists/GetByTitle(‘Trainings’)/GetItemById(2)
Get SharePoint logged in user information or current user information	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/currentUser
Get selected fields for SharePoint list items	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/web/lists/getbytitle(‘Trainings’)/Items?select=ID,Title,FirstName,LastName
Get all SharePoint site users	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/siteusers
Get all SharePoint groups from the site	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/sitegroups
Get particular SharePoint group by group id	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/sitegroups/GetById(GroupId)
Get all users from a SharePoint group	https://tsinfotechnologies.sharepoint.com/sites/SPGuides/_api/Web/sitegroups(Id)/users

SharePoint crud operations using Rest API

Now, let us check do a few examples related to SharePoint CRUD operations using Rest API. I will show you how to create an item in the SharePoint list using Rest API. Then will see how to update an item in a SharePoint list using Rest API. Then I have shown an example of how to delete a SharePoint list using Rest API. Finally, I will show you how to get all SharePoint list items using Rest API.

Below are examples of crud operations in SharePoint rest api. For the rest api code, we can add a script editor web part in a SharePoint Online web part page.

Get all SharePoint list items using Rest API

Let us first see how to get all list items using SharePoint rest api.

Here, I have added a button, and on button click, we can retrieve SharePoint list items using rest api and display them.

Here, you can see in the below code I have taken a button and, on click of that button, called the GetListItems() method. I am displaying all the SharePoint list items in a dialog box in the onSuccess method.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>

<button onclick="GetListItems();" type="button">Get All List Items​</button>

<script>
function GetListItems()
{
var url = _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists/getByTitle('Employees')/items";
$.ajax({
url: url,
type: "GET",
headers:
 {
"accept":"application/json; odata=verbose"
},
success: onSuccess,error: onError
});
}

function onSuccess(data) {
var items = data.d.results;
var allItems='';
for (var i = 0; i < items.length; i++) {
allItems+="Item ID- "+ items[i].Id+ " : Title- " + items[i].Title + '\r\n';
}
alert(allItems);
}

function onError(error) {alert(JSON.stringify(error));
}
</script>

Save the above code in a script editor web part and then click on the button; you can see the output below:

This is how we can get all list items in SharePoint Online using rest api.

Insert an item to SharePoint using rest api

Now, in the next part of the SharePoint rest api CRUD operation, we will see an example of the SharePoint rest api insert list item.

We will insert an item to the same SharePoint Online list. Here also, I have added button control, and once the user clicks on the button, the item will be inserted into the list using Rest API code.

Here, we have added a few new things:

POST: Here, it is going to be a HTTP POST request because it is an insert operation. For any kind of insert or update operation, we have use the HTTP POST request.

__REQUESTDIGEST: While doing any rest api POST operation, we need to send a valid request digest to the SharePoint page. This is a token, and it helps SharePoint to understand that the request is a valid request.

SharePoint always includes a request digest token on every page in a hidden field as __REQUESTDIGEST. So, while working with Rest API, we need to get this hidden value from the field and send it with the request in a parameter as X-RequestDigest. The token is valid for 30 minutes. It will be like the following:

"X-RequestDigest": $("#__REQUESTDIGEST").val()

It is a must for any kind of SharePoint rest api POST request.

Another important is the type which we do like below:

type: "SP.Data.EmployeesListItem"

Ideally, you should follow the below method to get it.

'SP.Data.' + 'List Internal Name' + 'ListItem'

Example: SP.Data.' + 'Employees' + 'ListItem' = SP.Data.EmployeesListItem

Below is the complete code to insert the item to SharePoint using rest api.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>

<button onclick="InsertItem();" type="button">Insert Item to SharePoint List​</button>

<script>
function InsertItem()
{
var restendpoint = _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists/getByTitle('Employees')/items";
$.ajax
({
url: restendpoint,
type: "POST",
data: JSON.stringify
(
{
__metadata:
{
type: "SP.Data.EmployeesListItem"
},
Title : "Bijay Kumar"
}),
headers:
{
"Accept": "application/json;odata=verbose",
"Content-Type": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"X-HTTP-Method": "POST"
},
success: function()
{
alert("Item added to the SharePoint list");
},
error: function()
{
alert("Error Occurred!");
}
});
}
</script>

Once you run the code and click on the button, you can see the item will be inserted to the SharePoint list.

Update an item in SharePoint list using Rest API

Now, let us see another example on SharePoint rest api update list item. Updating an item is almost similar to inserting an item into the SharePoint list; the only difference is the rest of the endpoint.

We need to get the item by id, and then we can update.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>

<button onclick="UpdateItem();" type="button">Update Item (ID=4)​</button>

<script>
function UpdateItem()
{
var restendpoint = _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists/getByTitle('Employees')/items/getbyid(4)";

$.ajax({  
    url: restendpoint,  
    type: "POST",  
    headers: {  
        "accept": "application/json;odata=verbose",  
        "X-RequestDigest": $("#__REQUESTDIGEST").val(),  
        "content-Type": "application/json;odata=verbose",  
        "IF-MATCH": "*",  
        "X-HTTP-Method": "MERGE"  
    },  
    data: "{__metadata:{'type':'SP.Data.EmployeesListItem'},Title:'Bhawana Rathore'}",
    success: function(data) {  
        alert('Item updated successfully!');
    },  
    error: function(error) {  
        alert(JSON.stringify(error));  
    }  
});  

}
</script>

Once you save the code and click on the button, it updates the list item whose id=5.

Here is another example on SharePoint rest api update list item by id.

Delete SharePoint list item using Rest API

Now, let us see another example of SharePoint crud operations using rest api on SharePoint rest api delete list item.

This will also be a POST operation, but we have to pass an additional parameter as “X-Http-Method”: “DELETE”.

The rest endpoint is the same as updating the list item because we will first get the item by id which item you want to delete.

Below is the complete code to delete SharePoint list items using Rest API.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>

<button onclick="DeleteItem();" type="button">Delete Item (ID=3)​</button>

<script>
function DeleteItem()
{
var restendpoint = _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists/getByTitle('Employees')/items/getbyid(3)";

$.ajax({  
    url: restendpoint,  
    type: "POST",    
    headers: {  
        "Accept": "application/json;odata=verbose",  
        "X-Http-Method": "DELETE",  
        "X-RequestDigest": $("#__REQUESTDIGEST").val(),  
        "If-Match": "*"  
    },  
    success: function(data) {  
        alert('SharePoint list item deleted');  
    },  
    error: function(data) {  
        alert('Error Occurred!');  
    }
});  

}
</script>

So this is an example of deleting a list item in SharePoint using Rest API.

SharePoint rest api __metadata

Let us see, the SharePoint rest api __metadata used for what purpose?

__metadata is very important while working with SharePoint rest api, especially while doing any HTTP POST operations like insert and update.

Through __metadata we provide various information required to create or update operations. Another important property we set is the type parameter.

For example, if you want to create a list in the SharePoint Online site by using Rest API, then we need to pass type=SP.List and other information like the list Title, Description, BaseTemplate, etc. It looks like below:

data:  JSON.stringify({ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true,
 'BaseTemplate': 100, 'ContentTypesEnabled': true, 'Description': 'This is the list description', 'Title': 'This is List Title' })

Similarly, if you want to create a site in SharePoint using Rest API, we have to pass the type= SP.WebInfoCreationInformation and we also need to pass other data required to create a site like Title, Description, Url, WebTemplate, Language, etc. It should look like below:

data: JSON.stringify(
        {'parameters': {
            '__metadata':  {'type': 'SP.WebInfoCreationInformation' },
            'Url': 'SiteURL',
            'Title': 'Site Title',
            'Description': 'Site Description,
            'Language':1033,
            'WebTemplate':'sts',
            'UseUniquePermissions':false}
        }
    )

This is why we use SharePoint rest api __metadata.

SharePoint Rest API Examples

Now, let us check out a few SharePoint rest API examples.

Filter SharePoint list items by the current user using Rest API

Here, I have a SharePoint online Announcement list with a Title column, and various users have inserted some data. The list looks like below:

Now, let us see, how to filter SharePoint list items by the current user using Rest API.

By using the _spPageContextInfo.userEmail, we are retrieving the current logged-in user email ID.

In the rest endpoint URL, we are filtering based on the current user email ID, which we are comparing with the Created By’s email ID field. The internal name of the Created By column in “Author”.

We can place the below code inside a SharePoint script editor web part, which can be added to a web part page.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" ></script>
<h1>Training Announcements</h1><br/>
<div id="result"></div>
<script>
var LoginName=_spPageContextInfo.userEmail;
var newURL="/_api/Web/Lists/GetByTitle('TrainingAnnouncements')/Items?$select=Title,ID,Author/EMail&$filter=Author/EMail eq '"+ LoginName +"'&$expand=Author/Id";
jQuery().ready(function () {
function getItems(url) {
return $.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "GET",
headers: {
"accept": "application/json;odata=verbose",
}
});
}
getItems( newURL).done(function(data){
var fullresult="";
data.d.results.forEach(function(item){ // no need for oldskool for loops
fullresult+=item.Title +'<br><br>';
});
jQuery('#result').html(fullresult);
});
});
</script>

Once you add the code, you can see the rest api filter records based on the current user.

Get SharePoint list items created by the current user with REST API

Let us see, another approach to get SharePoint list items created by the current user with Rest API.

In this SharePoint Rest API example, I have a SharePoint Online custom list as the Department is there. We will retrieve items created by the logged-in user from the department list.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" ></script>
<h1>Departments Added by Logged In User</h1><br/>
<div id="result"></div>
<script>
var userId = _spPageContextInfo.userId;
var newURL="/_api/Web/Lists/GetByTitle('Departments')/Items?$filter=AuthorId eq " + userId;
jQuery().ready(function () {
function getItems(url) {
return $.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "GET",
headers: {
"accept": "application/json;odata=verbose",
}
});
}
getItems( newURL).done(function(data){
var fullresult="";
data.d.results.forEach(function(item){ // no need for oldskool for loops
fullresult+=item.Title +'<br><br>';
});
jQuery('#result').html(fullresult);
});
});
</script>

I have added the code inside a script editor web part, and you can see the results below:

Get current user details using Rest API in SharePoint Online

Let us see, how to get current user details using Rest API in SharePoint Online. We can get user details like ID, user name, email ID, etc. The same code will work for SharePoint Online as well as SharePoint on-premises versions.

The Rest endpoint to retrieve current logged-in user details:

https://onlysharepoint2013.sharepoint.com/sites/SharePointSky/_api/web/currentuser

Similarly, if we want to retrieve specific properties like Email, LoginName, Title, UserID, etc, then we need to modify the endpoint URL to like below:

https://onlysharepoint2013.sharepoint.com/sites/SharePointSky/_api/web/currentuser?$select=Email,LoginName,Title,Id

By using the above rest endpoint we can retrieve only selected properties.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" ></script>
<input type="button" id="btnClick" value="Get User Details using Rest API"/>
<script>
$(function(){
$("#btnClick").click(function(){
GetUserDetails();
});
});
function GetUserDetails() {
var url = "https://onlysharepoint2013.sharepoint.com/sites/SharePointSky/_api/web/currentuser";
$.ajax({
url: url,
headers: {
Accept: "application/json;odata=verbose"
},
async: false,
success: function (data) {
alert("User Name: "+data.d.Title +" Email ID: " +data.d.Email+" User ID: " +data.d.Id);
},
eror: function (data) {
alert("An error occurred. Please try again.");
}
});
}
</script>

Once you run the above code, you can see the current user details below:

Here is another approach: we can get logged-in user details using Rest API in SharePoint Online.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js" ></script>
<h1>Logged In User Details</h1><br/>
<div id="result"></div>
<script>
var newURL="/_api/web/currentuser";
jQuery().ready(function () {
function getLoggedInUserDetails(url) {
return $.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "GET",
headers: {
"accept": "application/json;odata=verbose",
}
});
}
getLoggedInUserDetails(newURL).done(function(data){
var fullresult="";
fullresult+="User Name: "+data.d.Title +"<br><br>";
fullresult+="Email ID: "+data.d.Email +"<br><br>";
fullresult+="ID: "+data.d.Id +"<br><br>";
jQuery('#result').html(fullresult);
});
});
</script>

Once you run the above code, you can see the logged-in user details below in SharePoint.

How to use SharePoint rest api in a browser

Let us see now how to use SharePoint rest api in a browser.

We can put the rest endpoint in the browser, and we can see the result. Let us check what will happen when you put the rest endpoint in the browser.

https://tsinfotechnologies.sharepoint.com/sites/SPGuidesClassic/_api/web/lists/getByTitle('Employees')/items/getbyid(7)

Once you enter the URL, if you have not signed in, then it will give you the error message like Access denied. If you have already logged in, then you can see the output below in XML.

If you are trying to open the same SharePoint rest api endpoint in Internet explorer, you can see the output will come like this below:

Here is a video tutorial I have made on SharePoint Rest API crud operations.

Conclusion

I hope now you have an idea of how to use Rest API in SharePoint Online as well as SharePoint on-premises versions like SharePoint server 2019/2016, etc. We also check out a few SharePoint rest API examples.

You may also like:

• Create a SharePoint List using Rest API
• Display SharePoint list data using HTML and jQuery table using Rest API
• Retrieve SharePoint list items programmatically using jsom, rest api and csom