Getting Started with ListData.svc
Because ListData.svc has a RESTful architecture, you can use the browser and Fiddler to give it a test drive. To get started, just point your browser at the /_vti_bin/ListData.svc under your favorite site collection and append a list name to the end of the URL. The URL format looks like this:
http://{SiteCollectionUrl}/_vti_bin/ListData.svc/{ListName}
This will give you back an Atom feed that includes all of the list items in your list as shown below.
As you can see if you examine the category element on each list item, the service is using LINQ to SharePoint under the covers to access the list data. This allows you to write efficient queries just by manipulating the URL that you use to call the service. The LINQ to SharePoint layer handles the task of translating your request into a CAML query before retrieving the list data and returning the results.
For example, if I want only the employees who are members of the Development team and I want the results ordered by job title, I would append the query string “?$filter=(Team eq ‘Development’)&$orderby=JobTitle”.
The sorted, filtered results are shown below.
The LINQ to SharePoint layer translates this query string into a CAML query that looks something like this.
<Query>
<OrderBy>
<FieldRef Name=”JobTitle” Ascending=”TRUE”></FieldRef>
</OrderBy>
<Where>
<Eq>
<FieldRef Name=”Team”></FieldRef>
<Value Type=”Text”>Development</Value>
</Eq>
</Where>
</Query>
As you can see, the query string syntax is significantly more compact than the CAML syntax making it much easier to write.
After exploring the service in the browser, the next step is to open up Fiddler to investigate what is possible by modifying the request headers and HTTP verb. First, use the request builder to add an Accept header with the value “application/json”. This will cause the service to return a JSON serialized object instead of an Atom.
Next, switch over to the response viewer to see the JSON data returned by the service. This data is ready to be serialized into a JavaScript object that allows easy access to the list items that match your query.
You can also try executing create, update, and delete operations on your list items with the POST, PUT, and DELETE verbs using the request builder.
Using ListData.svc in Your Application
Now that you know how to work with the service, you can integrate it into your AJAX application using JavaScript. The sample code below shows the basic steps needed to call the web service and handle the results.
First you use the Sys.Net.WebRequest class to make the web service call. Be sure to set the verb, url, and Accept header. Also, set a handler function for the completed event. This function will be called when the request is complete.
function load()
{
var request = new Sys.Net.WebRequest();
request.set_httpVerb(“GET”);
request.set_url(“http://moss.contoso.com/sites/Lab05/_vti_bin/ListData.svc/Employees?$filter=(Team eq
‘Development’)&$orderby=JobTitle
request.get_headers()[‘Accept’] = ‘application/json’;
request.add_completed(handleRequestComplete);
request.invoke();
}
In the handler function you use the response object which is passed in as the first parameter to get at the JSON data returned by the server. The JSON data is serialized into a JavaScript object by calling the get_object() method on the response object. Once you have the object, you can use it to render the data in whatever way you need. In my simple example, I show the first employee’s name in an alert box.
function handleRequestComplete(response, userContext)
{
var employee = response.get_object().d[0];
alert(employee.Fullname);
}
The last thing your script needs to do is wire up the load function as a handler for the Application’s load event.
Sys.Application.add_load(load);
For a more object-oriented approach, you can use the Sys.Data.AdoNetDataContext from the ASP.NET AJAX 4.0 library. For more on this approach, check out this blog post at Lost In Tangent.
Although ListData.svc is great for AJAX applications it can also be used in Silverlight applications and .NET clients using the System.Data.Services.Client namespace. The ADO.NET Data Services team has videos on how to do this in both a Silverlight application and a .NET application. Using the service from .NET code is even easier than in JavaScript because you can take full advantage of LINQ and control databinding.
