List Items manipulation via REST API in SharePoint 2010

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.

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:

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:

  1. “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).
  2. “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.

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:

References

Advertisements

21 thoughts on “List Items manipulation via REST API in SharePoint 2010

  1. 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?

  2. 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!

      • 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.

  3. 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” ?

  4. 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.

  5. 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.

  6. 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.

  7. 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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s