Early this morning about 6:17 AM I sat up in my office chair and said to myself "it can't really be this easy". But it is.

Here's my scenario. I am in need of writing client-side code in JavaScript which adds new items to a SharePoint 2010 Contacts list named Customers. I have been told that I'm required to accomplish this using the Open Data Protocol (OData) and the new REST-based API accessible through ListData.svc. This means I must add each item to a SharePoint list using an HTTP POST operation.

At first, I thought my inner code monkey would be challenged by writing the JavaScript required to reach my goal. However, for the last few months I have been hearing talk on the streets about this cool new JavaScript library named datajs - JavaScript Library for data-centric web applications. I can say first hand that it's powerful and that it's simple to use. Take a look at the following JavaScript code and notice how I create a new JavaScript object and initialize it with properties that match up to the names of the columns I need to modify in the target list.

function OnAddCustomer() {   

  // create a JavaScript object with field values for the new item
  var newCustomer = {
    LastName: $("#txtLastName").val(),     
    FirstName: $("#txtFirstName").val()
  };

  // create JavaScript object required as a parameter to OData.request()
  var requestOptions = {
    requestUri: GetWebUrl() + "_vti_bin/ListData.svc/Customers",
    method: "POST",
    data: newCustomer
  };

  // call OData.request to add item with HTTP POST operation
  OData.request(requestOptions, OnAddSuccess, OnAddError);
}

You can see that I am building an URL for the requestUri value by calling a helper function named GetWebUrl. I wrote this function to take the Web-relative URL from the _spPageContextInfo variable and to add a forward slash at the end if it's not already there.

function GetWebUrl() {
  var webUrl = _spPageContextInfo.webServerRelativeUrl;
  if (webUrl.substr(webUrl.length - 1, 1) != "/") {
    webUrl += "/";
  }
  return webUrl; 
}

The full requestUri value is built from the Web-relative URL parsed together with the relative path to ListData.svc and the list name which in my case is Customers. Once I have built the requestOptions object, I pass it in the call to the OData.request method along with two other parameters with callback methods that execute either after the POST operation completes successfully or with an error.

OData.request(requestOptions, OnAddSuccess, OnAddError);

One of these two callback methods will be executed once response to the HTTP POST operation is returned from the Web server.

function OnAddSuccess(data, request) {
  // handle success - reinitialize the user interface 
  $("#txtLastName").val("");   
  $("#txtFirstName").val("").focus();
}

function OnAddError(error) {
  // handle error - notify user that something went wrong
  alert(JSON.stringify(error));
}

It's wonderful how little code you have to write to add items using the OData.request method. You can use Fiddler on your developer workstation to see what's going on behind the scenes and figure out what is actually being sent across the network to Web server.

Svweet!