REST service for list was first introduced in SharePoint 2010. It was under the end point /_vti_bin/listdata.svc and it still works in SharePoint 2013. SharePoint 2013 introduces another endpoint /_api/web/lists and which is much more powerful than in SharePoint 2010. The main advantage of REST in SharePoint 2013 is: we can access data by using any technology that supports REST web request and Open Data Protocol (OData) syntax. That means you can do everything just making HTTP requests to the dedicated endpoints. Available HTTP methods are GET, POST, PUT, MERGE, and PATCH. Data format supported by the HTTP methods is ATOM (XML based) or JSON.
CREATE: Any kind of create operation like list, list item, site and so on maps to the HTTP POST method. You have to specify the data in request body and that’s all. For non-required columns, if you do not specify the values, then they will be set to their default values. Another important thing is: you cannot set value to the read-only fields. If you do so, then you will get an exception.
UPDATE: For updating existing SharePoint 2013 objects, there are three HTTP methods like PUT, PATCH and MERGE available. The recommended methods are PATCH and MERGE. PUT requires the entire huge object to perform update operation. Let's say we have a list named EMPLOYEE and it has 100+ fields and we want to update EmployeeName field only. In this case, if we use PUT method, we must have to specify the value of others fields alone with EmployeeName field. But PATCH and MERGE are very easy. We just have to specify the value of EmployeeName filed only.
For accessing SharePoint resources by using REST API, at first we have to find the appropriate endpoints. The following table demonstrates the endpoints associated with CRUD operation in a list.
In the above _spPageContextInfo.webAbsoluteUrl may be quite new to you. Actually, it returns the site url and it’s the preferred way rather typing it hard coded. Now it’s time to constructs some urls and call the above method.
Getting All Items from SpTutorial
If we go through the REST endpoints table again, the endpoint (constructed url) should look like the following.
Hide Copy Code
var urlForAllItems = "/_api/Web/Lists/GetByTitle('SpTutorial')/Items";
Call the method getItems(urlForAllItems);
In the data.d.results, you will find fields internal names as object’s property. In the above example, we will get only the Id of Lookup and Person type column. But we need more information about these columns in ourJSON results. To nail this, we have to learn some OData query string operators.
$select specifies which fields to return in JSON results.
$expand helps to retrieve information from Lookup columns.
Now if we re-write the urlForAllItems, it should look like the following:
Hide Copy Code
var urlForAllItems =
"/_api/Web/Lists/GetByTitle('SpTutorial')/Items?"+
"$select=ID,Title,SpMultiline,SpChoice,SpNumber,SpCurrency,SpDateTime,SpCheckBox,SpUrl,"+
"SpPerson/Name,SpPerson/Title,SpLookup/Title, SpLookup/ID" +
"&$expand=SpLookup,SpPerson";
To use $expand alone with $select, you have to specify the column names in $select just what I did in the above like SpLookup/Title, SpLookup/ID.
$filter specifies which items to return. If I want to get the items where Title of SpTutorial equals to‘first tutorial’ and ID of SpTutorialParent equals to 1, the URL should look like the following:
Hide Copy Code
var urlForFilteredItems =
"/_api/Web/Lists/GetByTitle('SpTutorial')/Items?"+
"$select=ID,Title,SpMultiline,SpChoice,SpNumber,SpCurrency,SpDateTime,SpCheckBox,SpUrl,"+
"SpPerson/Name,SpPerson/Title,SpLookup/Title,SpLookup/ID"+
"&$expand=SpLookup,SpPerson&$filter=Title eq 'first tutorial' and SpLookup/ID eq 1";
You may notice that I have used a query operator like ‘eq’ in above URL. Now let’s see what are the other query operators available.
| Numeric | String | Date Time functions |
Lt (less than) | startsWith (if starts with some string value) | day() |
Le (less than or equal) | substringof ( if contains any sub string) | month() |
Gt (greater than) | | year() |
Ge (greater than or equal) | | hour() |
Eq (equal to) | Eq | minute() |
Ne (not equal to) | Ne | second() |
Note: Unfortunately, date time functions do not work with new style (URL) of SharePoint 2013. But there is a hope we can do it like SharePoint 2010 style.
Hide Copy Code
var filterByMonth = "/_vti_bin/listdata.svc/SpTutorial?$filter=month(SpDateTime) eq 6";
$orderby is used to sort items. Multiples fields are allowed separate by comma. Ascending or descending order can be specified just by appending the asc or desc keyword to query.
Hide Copy Code
var urlForOrderBy = "/_api/Web/Lists/GetByTitle('SpTutorial')/Items?" +
"$select=ID,Title,SpMultiline,SpChoice,SpNumber,SpCurrency,SpDateTime,SpCheckBox,SpUrl," +
"SpPerson/Name,SpPerson/Title,SpLookup/Title,SpLookup/ID" +
"&$expand=SpLookup,SpPerson&$orderby=ID desc";
$top is used to apply paging in items.
Hide Copy Code
var urlForPaging = "/_api/Web/Lists/GetByTitle('SpTutorial')/Items?$top=2";
Adding New item: In this case, our HTTP method will be POST. So write a method for it.
Hide Copy Code
function addNewItem(url, data) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "POST",
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose"
},
data: JSON.stringify(data),
success: function (data) {
console.log(data);
},
error: function (error) {
alert(JSON.stringify(error));
}
});
}
In header, you have to specify the value of X-RequestDigest. It’s a hidden field inside the page, you can achieve its value by the above mentioned way ($("#__REQUESTDIGEST").val()). But sometimes, it does not work. So the appropriate approach is to get it from /_api/contextinfo. For this, you have to send aHTTP POSTrequest to this URL (_api/contextinfo) and it will return X-RequestDigest value (in the JSON result, its name should be FormDigestValue).
URL and request body will be like the following for adding new item in list.
Hide Copy Code
var addNewItemUrl = "/_api/Web/Lists/GetByTitle('SpTutorial')/Items";
Hide Copy Code
var data = {
__metadata: { 'type': 'SP.Data.SpTutorialListItem' },
Title: 'Some title',
SpMultiline: 'Put here some multiline text. You can add here some rich text also',
SpChoice: 'Choice 3',
SpNumber: 5,
SpCurrency: 34,
SpDateTime: new Date().toISOString(),
SpCheckBox: true,
SpUrl: {
__metadata: { "type": "SP.FieldUrlValue" },
Url: "http://test.com",
Description: "Url Description"
},
SpPersonId: 3,
SpLookupId: 2
};
Note: Properties of data are the internal name of the fields. We can get it from following URL by making aHTTP GET request.
Hide Copy Code
var urlForFieldsInternalName = "/_api/Web/Lists/GetByTitle('SpTutorial')/
Fields?$select=Title,InternalName&$filter=ReadOnlyField eq false";
| Type | Value |
Single line of text | String |
Multiple lines of text | Multiple lines can be added here also rich text |
Choice | String but it must come from choices available in the list. |
Number | Integer or double |
Currency | Like number |
Date and Time | String but it must be ISOString format |
Lookup | Integer and must be the ID of Lookup item |
Yes/No | true or false |
Person or Group | Integer and must be the ID of Person or Group |
Hyperlink or Picture | Object that has three properties only like__metadata, Url, Description |
Inserting multiple values to person or group column, we have to specify the ids of people or group.
Hide Copy Code
var data = {
__metadata: { "type": "SP.Data.TestListItem" },
Title: "Some title",
MultiplePersonId: { 'results': [11,22] }
}
N.B.: This is an update based on user comment.
How to specify the value of __metadata for new list item? Actually, it looks like the following.
__metadata: {'type': 'SP.Data.' + 'Internal Name of the list' + 'ListItem'}
Updating Item: We can use the following method for updating an item.
Hide Copy Code
function updateItem(url, oldItem, newItem) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "PATCH",
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"content-Type": "application/json;odata=verbose",
"X-Http-Method": "PATCH",
"If-Match": oldItem.__metadata.etag
},
data: JSON.stringify(newItem),
success: function (data) {
console.log(data);
},
error: function (error) {
alert(JSON.stringify(error));
}
});
}
Then can get your old item, modify it and construct the URL.
Hide Copy Code
var updateItemUrl = "/_api/Web/Lists/GetByTitle('SpTutorial')/
getItemById('Id of old item')";
Something has been changed as compared to add new item. Let me explain one by one. Now HTTP method isPATCH and it is also specified in header ("X-Http-Method": "PATCH") and which is recommended I mentioned earlier.
etag means Entity Tag which is always returned during HTTP GET items. You have to specify etag value while making any update or delete request so that SharePoint can identify if the item has changed since it was requested. Following are the ways to specify etag.
"If-Match": oldItem.__metadata.etag (If etag value does not match, service will return an exception)"If-Match": "*" (It is considered when force update or delete is needed)
Deleting Item
It’s very simple. Just the following method can do everything.
Hide Copy Code
function deleteItem(url, oldItem) {
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + url,
type: "DELETE",
headers: {
"accept": "application/json;odata=verbose",
"X-RequestDigest": $("#__REQUESTDIGEST").val(),
"If-Match": oldItem.__metadata.etag
},
success: function (data) {
},
error: function (error) {
alert(JSON.stringify(error));
}
});
}
URL is the same as updating item. It will not return anything when operation is successful. But if any error happens, then it will return an exception.
