Introduction
Apart from CSOM API, REST API introduces another approach to access SharePoint list data from platforms on which the CSOM may be unavailable. The SharePoint REST interface is based on the REST-based Open Data protocol (OData) which is a platform-independent open standard.
Examples
This section contains sample code for all of the CRUD operations.
Create
In order to perform a Create operation via REST, you must perform the following actions:
- Create an HTTP request using the POST verb.
- Use the service URL of the list to which you want to add an entity as the target for the POST.
- Set the content type to application/json.
- Serialize the JSON objects that represent your new list items as a string, and add this value to the request body.
The following code snippet demonstrates how to perform a Create operation against a SharePoint list.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| function createListItem(webUrl,listName, itemProperties, success, failure) { | |
| $.ajax({ | |
| url: webUrl + "/_vti_bin/listdata.svc/" + listName, | |
| type: "POST", | |
| processData: false, | |
| contentType: "application/json;odata=verbose", | |
| data: JSON.stringify(itemProperties), | |
| headers: { | |
| "Accept": "application/json;odata=verbose" | |
| }, | |
| success: function (data) { | |
| success(data.d); | |
| }, | |
| error: function (data) { | |
| failure(data.responseJSON.error); | |
| } | |
| }); | |
| } | |
| //Usage: create task | |
| var taskProperties = { | |
| 'TaskName': 'Order Approval', | |
| 'AssignedToId': 12 | |
| }; | |
| createListItem('https://contoso.sharepoint.com/project/','Tasks',taskProperties,function(task){ | |
| console.log('Task' + task.TaskName + ' has been created'); | |
| }, | |
| function(error){ | |
| console.log(JSON.stringify(error)); | |
| } | |
| ); |
Read
In order to perform a Read operation via REST, you must perform the following actions:
- Create an HTTP request using the GET verb.
- Use the service URL of the list item to which you want to add an entity as the target for the GET.
- Set the content type to application/json.
The code sample demonstrates of how to retrieve an item based on its ID:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| function getListItemById(webUrl,listName, itemId, success, failure) { | |
| var url = webUrl + "/_vti_bin/listdata.svc/" + listName + "(" + itemId + ")"; | |
| $.ajax({ | |
| url: url, | |
| method: "GET", | |
| headers: { "Accept": "application/json; odata=verbose" }, | |
| success: function (data) { | |
| success(data.d); | |
| }, | |
| error: function (data) { | |
| failure(data.responseJSON.error); | |
| } | |
| }); | |
| } | |
| //Usage | |
| getListItemById('https://contoso.sharepoint.com/project/','Tasks',2,function(taskItem){ | |
| console.log(taskItem.TaskName); | |
| }, | |
| function(error){ | |
| console.log(JSON.stringify(error)); | |
| } | |
| ); |
Update
To update an existing entity, you must perform the following actions:
- Create an HTTP request using the POST verb.
- Add an X-HTTP-Method header with a value of MERGE.
- Use the service URL of the list item you want to update as the target for the POST
- Add an If-Match header with a value of the entity’s original ETag.
In contrast to reading list item to update an item you will need to pass the eTag value, which could be obtained during item read.
About eTags
When updating or deleting items within SharePoint lists via REST you must specify the Entity Tag (eTag) value that was returned with the item during the initial query. This enables SharePoint to determine if the item has changed since it was requested. Alternatively you can tell SharePoint to perform the operation regardless by specifying * as the eTag value. For example:
- “If-Match”: item.__metadata.etag can be used to specify the actual eTag value (‘item’ is the object returned from SharePoint containing the list item in JSON format).
- “If-Match”: “*” can be used to match any eTag value resulting in the operation being performed regardless of the actual value.
They form part of the Ajax call for updating an item. eTags are part of the HTTP Protocol V1.1, more information on the topic can be found here.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| function updateListItem(webUrl,listName,itemId,itemProperties,success, failure) | |
| { | |
| getListItemById(webUrl,listName,itemId,function(item){ | |
| $.ajax({ | |
| type: 'POST', | |
| url: item.__metadata.uri, | |
| contentType: 'application/json', | |
| processData: false, | |
| headers: { | |
| "Accept": "application/json;odata=verbose", | |
| "X-HTTP-Method": "MERGE", | |
| "If-Match": item.__metadata.etag | |
| }, | |
| data: Sys.Serialization.JavaScriptSerializer.serialize(itemProperties), | |
| success: function (data) { | |
| success(data); | |
| }, | |
| error: function (data) { | |
| failure(data); | |
| } | |
| }); | |
| }, | |
| function(error){ | |
| failure(error); | |
| }); | |
| } | |
| //Usage: set Task Name & AssignedTo | |
| var taskProperties = { | |
| 'TaskName': 'Approval', | |
| 'AssignedToId': 12 | |
| }; | |
| updateListItem('https://contoso.sharepoint.com/project/','Tasks',2,taskProperties,function(item){ | |
| console.log('Task has been updated'); | |
| }, | |
| function(error){ | |
| console.log(JSON.stringify(error)); | |
| } | |
| ); |
Delete
To delete an entity, you must perform the following actions:
- Create an HTTP request using the POST verb.
- Add an X-HTTP-Method header with a value of DELETE.
- Use the service URL of the list item you want to update as the target for the POST
- Add an If-Match header with a value of the entity’s original ETag.
The Delete operation is similar to Update operation, the code below demonstrates how to perform a Delete operation:
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| function deleteListItem(webUrl, listName, itemId, success, failure) { | |
| getListItemById(webUrl,listName,itemId,function(item){ | |
| $.ajax({ | |
| url: item.__metadata.uri, | |
| type: "POST", | |
| headers: { | |
| "Accept": "application/json;odata=verbose", | |
| "X-Http-Method": "DELETE", | |
| "If-Match": item.__metadata.etag | |
| }, | |
| success: function (data) { | |
| success(); | |
| }, | |
| error: function (data) { | |
| failure(data.responseJSON.error); | |
| } | |
| }); | |
| }, | |
| function (error) { | |
| failure(error); | |
| }); | |
| } | |
| //Usage: delete Task with Id=3 | |
| deleteListItem('https://contoso.sharepoint.com/project/','Tasks',3,function(){ | |
| console.log('Task has been deleted'); | |
| }, | |
| function(error){ | |
| console.log(JSON.stringify(error)); | |
| } | |
| ); |
YASP Blog 
Vadim,
This is great and very helpful! I’ve been able to successfully use your “Create” instructions to create list items. Except when it comes to creating Folders. When I create a folder, the title field is displaying the item ID# and not the text I set as the folder name.
I’m using var itemProperties = {“Title”: “Test Fodler”,”ContentType”:”Folder”} ;
any ideas?
Hi Chris,
please follow my answer on SharePoint SE, it demonstrates how to create a Folder using SharePoint 2010 REST Interface 😉
Thanks! That’s a great article too! For some reason it never came up in any of my searches. Anyway, I did find an answer on my own. Not only was it necessary to specify the ContentType value but I also had to specify the ContentTypeID value. Then the link field would show the proper value.
Best to you!
How can I get/update (download/upload) content of files using the approach described?
Hey Andrii,
could you please post a corresponding question in SharePoint SE?
well, actually I have already find a way, but since there is not “answer my question” button here, I did not respond.
I use GET with file URL for reading and PUT (via POST) to “_vti_bin/ListData.svc/ListName(file_id)/$value” for writing with “Content-type:application/octet-stream” and “If-Match:*” + “X-HTTP-Method:PUT” headers.
Really informative blog article.Really thank you! Want more. afecdgfckdfdfbed
Thanks for this clearly defined post! Are you able to retrieve associated page images where applicable with this approach?
Thanks for this clearly defined post! Are you able to retrieve associated page images where applicable with this approach?
*forgot to check the notify via email for replies box
Is there any special steps I need to follow when creating a list item that uses a rich text field? Let’s say the source of the rich text field is this: Click me
What would the syntax of the create statement need to be, if the rich text field was called “Information” ?
Rich text is just ASCII in the end. If you stringify properly it should work.
its give me 500 Internal server error when i update the checkin items. It works fine with checkout items
Thank you very much. Would you know by any chance how to use the “SP.Utilities.Utility.SendEmail” service? I’m trying to connect to SP.Utilities.Utility.SendEmail but I always get an error.
Sorry for the double post, I thought the first one had gone lost. 😦
No worries, i will take a look on how “SP.Utilities.Utility.SendEmail is supposed to work and get back to you 😉
I’ve been trying for two days. I quit. Please tell me if you find something 😦
Thank you for the detailed instructions. Would you know by any chance how to use the “SP.Utilities.Utility.SendEmail” service? I’ve tried, but the only solutions I find do only work for Sharepoint 2013 and I’m stuck with 2010.
Did you get this working SP.Utilities.Utility.SendEmail with Sharepoint 2010?
Your code Read error
REST_API.aspx
SCRIPT5007: Unable to get property ‘error’ of undefined or null reference
REST_API.aspx, line 777 character 13
Thanks Vadim for your post,
do you have any idea how can i apply deferred technic to your read item method. i have look up columns (single/multi) in my list and i want to be able to load them and use them.
Thanks for your post. It’s been very helpful.
In your createListItem() how would you check readyState and status before posting. I can create a list item but I also get {“readyState”:0,”responseText”:””,”status”:0,”statusText”:”error”} in the console.
If I step through the code in developer tools there are no errors thrown.
hi Vadim,
Thanks for your article.
Can you please help, how to use this code, in a .html file , that’s residing in the SP 2010 site assets library? i tried to add your code in a a html file, and referred this code from a site page’s content editor web part. but it didnt work.
Am i missing something? Do i need to refer any jQuery file’s reference?