Introduction to querying lists with REST and ListData.svc in SharePoint 2010

CoreyRoth — Thu, 21 Jan 2010 20:04:34 GMT

What I really like about SharePoint 2010 is all of the new ways we can get at list data. You can always use the Client Object Model, Linq to SharePoint, or the existing object model, but one neat new way to get at list data is with listdata.svc. ListData.svc provides a way of getting information from a list (or lists using joins) using REST. What you end up with is a nice RSS feed of list data, that you can consume with whatever client you would like. You can construct URLs in various manners to get specific records, do joins, or perform simple queries. I won’t go through everything that you can do with it today, but I’ll point you towards resources to do the more advanced things.

When you are getting started, the first thing you want to do is check and see if you have ListData.svc up and running. Like any SharePoint web service, it’s located in the _vti_bin folder of any existing site, so it will work with items relative to that site. Here is what a typical URL might look like.

http://<sharepoint-server>/_vti_bin/ListData.svc

Try hitting that URL on your SharePoint 2010 server and see if it works. There is a good chance that you will get a 404 error. This happened to me, so I did some searching and found Rob Garret’s post stating to go out and install ADO.NET Data Services 1.5 CTP 2. There are a few choices, but I have seen others recommend you go with the runtime only. I had issues installing the full package. Once you have it installed, it still didn’t work for me, so I rebooted my server and everything worked fine when it booted back up. My guess is you probably could just reset IIS though.

Once you have a working ListData.svc, hitting it you should get results like this.

You get an XML document of all lists available to be queried. If you notice the href on each collection it gives you an idea of how you can construct subsequent URLs to get data. In today’s example, we’re going to work with a simple task list. We’ll look at the various ways we can get data from this list.

To get the data for this list via REST we simply just add the list name to the URL. In my case the name of the list is called Tasks. Here is what the URL would look like.

http://<sharepoint-server>/_vti_bin/ListData.svc/<ListName>

In my case:

http://sp2010/_vti_bin/ListData.svc/Tasks

Here is what the results look like.

As you can see we get an RSS feed and this is how Internet Explorer renders it. However, if we look at the actual XML of the feed, we’ll find that we get quite a bit of data back about the list. Here is a snippet of the XML.

<feed xml:base="http://sp2010/_vti_bin/ListData.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Tasks</title>
  <id>http://sp2010/_vti_bin/ListData.svc/Tasks</id>
  <updated>2010-01-21T19:21:27Z</updated>
  <link rel="self" title="Tasks" href="Tasks" />
  <entry m:etag="W/&quot;1&quot;">
    <id>http://sp2010/_vti_bin/ListData.svc/Tasks(1)</id>
    <title type="text">Test 1</title>
    <updated>2010-01-21T09:26:51-06:00</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="TasksItem" href="Tasks(1)" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Attachments" type="application/atom+xml;type=feed" title="Attachments" href="Tasks(1)/Attachments" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Predecessors" type="application/atom+xml;type=feed" title="Predecessors" href="Tasks(1)/Predecessors" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Priority" type="application/atom+xml;type=entry" title="Priority" href="Tasks(1)/Priority" />
    <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Status" type="application/atom+xml;type=entry" title="Status" href="Tasks(1)/Status" />
    <category term="Microsoft.SharePoint.DataService.TasksItem" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:ID m:type="Edm.Int32">1</d:ID>
        <d:ContentTypeID>0x01080085FF0E1548B7414787A693232497B24E</d:ContentTypeID>
        <d:ContentType>Task</d:ContentType>
        <d:Title>Test 1</d:Title>
        <d:Modified m:type="Edm.DateTime">2010-01-21T09:26:51</d:Modified>
        <d:Created m:type="Edm.DateTime">2010-01-21T09:26:51</d:Created>
        <d:CreatedByID m:type="Edm.Int32">1</d:CreatedByID>
        <d:ModifiedByID m:type="Edm.Int32">1</d:ModifiedByID>
        <d:Owshiddenversion m:type="Edm.Int32">1</d:Owshiddenversion>
        <d:Version>1.0</d:Version>
        <d:Path>/Lists/Tasks</d:Path>
        <d:PriorityValue>(2) Normal</d:PriorityValue>
        <d:StatusValue>In Progress</d:StatusValue>
        <d:Complete m:type="Edm.Double" m:null="true" />
        <d:AssignedToID m:type="Edm.Int32" m:null="true" />
        <d:TaskGroupID m:type="Edm.Int32" m:null="true" />
        <d:Description>&lt;div&gt;Test 1 Task&lt;/div&gt;</d:Description>
        <d:StartDate m:type="Edm.DateTime">2010-01-21T00:00:00</d:StartDate>
        <d:DueDate m:type="Edm.DateTime" m:null="true" />
      </m:properties>
    </content>
  </entry>

As you can see in the content element, we can see the various site columns on a particular list item. Of course, there is more we can do with REST than just view everything in a list. If you want a specific item, you can use parenthesis and specify an indexer. Note that it is unit-indexed, not zero-indexed.

http://<sharepoint-server>/_vti_bin/ListData.svc/<ListName>(<Index>)

In my case:

http://sp2010/_vti_bin/ListData.svc/Tasks(3)

However, when you do this, Internet Explorer will give you an error that it cannot display this feed.

Not to worry though, if you view source, you still have a working XML document. It will pretty much look like the one above minus the initial feed information. You can take the query above and go one step further. Say, you just want to know the status for a specific task (note that the site column is actually called StatusValue here), you can simply add it to the URL like this.

http://<sharepoint-server>/_vti_bin/ListData.svc/<ListName>(<Index>)/(<Field>)

In my case:

http://sp2010/_vti_bin/ListData.svc/Tasks(3)/StatusValue

You’ll get an even simpler XML document that looks like this. It will create an element named after whichever site column you passed to it.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<StatusValue xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">Completed</StatusValue>

The last thing I will cover is simple queries. You can do this with $filter. There are a number of operators you can use here, but the one I will start with today is eq (or equals). For example, say I want to see all tasks that are completed, I would use a URL like this. Put any literals inside quotes.

http://sp2010/_vti_bin/ListData.svc/Tasks?$filter=StatusValue eq 'Completed'

This returns results that look like this and of course the content element in the XML has the complete data on each list item returned.

You can also use various other types of predicates, such as ne, gt, ge, lt, le, and, or, not, etc. What each one does is probably pretty obvious, but if its not take a look at this MSDN reference for more information on the various filters and parameters you can use. Skip the code stuff at the begging and scroll down a bit to find the good stuff. This is a good start to working with REST in SharePoint, but this really is just the tip of it. What you are learning here isn’t really just specific to SharePoint but it applies to anything you do with ADO.NET Data Services, so it might be useful elsewhere later.

One thing I will point out is that I was not able to use this with an external list. I am guessing this is by design (which sucks), but it doesn’t look like it’s going to work. Of course, my install could just be broken or this could be subject to change.

Corey Roth [MVP] : SharePoint, SP2010 Beta, REST

Introduction to querying lists with REST and ListData.svc in SharePoint 2010