Corey Roth [MVP] : REST

How to: Sort search queries in SharePoint 2013

CoreyRoth — Thu, 03 Jan 2013 20:58:54 GMT

Sorting search results has always been an interesting subject in SharePoint. It was actually harder to do than you would think. In SharePoint 2007, all you had was relevance and modified date (write). The KeywordQuery class did not have anything to allow you to sort. You could get around this though by using SQL Syntax though but it was not ideal. As a reminder, you should stop using SQL Syntax now. In SharePoint 2010, Microsoft added a SortList property to the KeywordQuery class however, if you tried to use it, you would likely get the error: Exception from HRESULT: 0x80040E60. This is because, code was added to prevent SharePoint 2010 to sort on anything but relevance and modified date. The only way to get sortable search results was to add FAST Search for SharePoint (FS4SP). That was unfortunate as many people wanted to sort but did not want to make that kind of investment.

Fast forward to today, and now we can take advantage of the SortList property and it really works. Let’s build off of my previous KeywordQuery post. All we need to do is add items to the read-only SortList collection. For example, to sort by author, we would add the following line before executing the query with SearchExecutor.

keywordQuery.SortList.Add("Author", SortDirection.Ascending);

Now the results are sorted by author.

We could also sort in descending order as well. For example to show files largest to smallest, use this snippet.

keywordQuery.SortList.Add("Size", SortDirection.Descending);

Here are the results:

These can be combined as well.

keywordQuery.SortList.Add("Author", SortDirection.Ascending);
keywordQuery.SortList.Add("Size", SortDirection.Descending);

The results then look like:

We can invoke this functionality when using the Search REST API as well. To do this, we use the querytext parameter to issue our query just like before, but we add the sortlist parameter. The syntax of the parameter is “manageproperty:sortorder”. For sort order you must specify ascending or descending. Be sure to include the values in single quotes. We delimit multiple sort properties using a comma (,). Using the above sort example, here is what the query string would look like.

http://server/_api/search/query?querytext='SharePoint'&sortlist='author:ascending,size:descending'&selectproperties='Title,Author,Size,Path,Write'

From the screenshot, you can see the PowerPoint Presentation is also the top result. I’ve also included a few selectproperties to make the results more legible.

I’m really excited that all users of SharePoint search now have this capability. It really adds a lot of value to the solutions that we can deliver. The last thing I will mention is that you must have the managed property you are searching on marked as sortable. I’ll talk about new features of managed properties in a post pretty soon.

How to: Use the SharePoint 2013 REST API from a Windows Store App (Windows 8 Metro)

CoreyRoth — Fri, 28 Sep 2012 14:52:13 GMT

I’ve recently taken an interest to building Windows Store Apps (aka Windows 8 Metro). Not because I think I can get rich in the Windows Store but because I think it provides a unique way to present SharePoint data. If you’re like me, you probably assumed Windows Store App development was just like .NET Framework 4.5 development. You would be wrong. The .NET Framework is provided by a single assembly reference called .NET for Windows Store Apps. It has many of the familiar classes that you have come to expect. My initial thinking was that I could use the SharePoint Client Object Model directly from my app. That thinking was also wrong. It turns out that the Client Object Model has a dependency on System.Web.Service.dll which does not exist in .NET for Windows Store Apps. Simply put, Window Store Apps only support WCF references. This means that the REST API is now our best choice.

When it comes to Windows Store Apps, you have a few choices on which programming language to use. Modern JavaScript is not my strong point, so I am going to demonstrate using C#. Before we dig into the C# code though, we’ll take a look at how to construct the REST URL. This article on MSDN does a great job explaining the details of how the URL is built. Essentially we start with the URL to our site (i.e.: http://server/site) and append /_api/web/lists to it along with a method to get a particular list by title, getbytitle. To get the items of the list we append /items to it. In my case, I want to pull the tasks list of a site so it would look something like this.

http://server/site/_api/web/list/getbytitle(‘tasks’)/items

You can type this right into your browser and see the XML that the REST API returns. Here’s an example.

There is a lot of XML to take in there. We’re particularly interested in the content element contain in each entry element. This has the data from our list items. However, we can reduce the amount of XML returned significantly by using the $select parameter on the REST URL. In my case I am going to select a few common fields such as Title, DueDate, and Status. Here is what the URL looks like now.

http://server/site/_api/web/list/getbytitle(‘tasks’)/items?$select=Title,DueDate,Status,PercentComplete

You’ll notice that the results are much more manageable now. We’ll talk about how we can use LINQ to XML here shortly to parse this data into something usable from our Windows Store app.

Now let’s look at the code that is required to get the data in our app. Start by creating a new Windows Store App in Visual Studio 2012. You can do this by choosing your language (C#) and then Windows Store –> Blank App (XAML).

If this is the first Windows Store App you have started in Visual Studio, you will be prompted for your Windows Live credentials. This allows you to get a certificate so that you can build apps locally. In our app, we want to bind data, so I am going to create a new Items Page. This template has many of the components you need to get started quickly with data binding.

When adding the page, you will be prompted to add some dependent files. Click yes and then you should see your design surface. Now, open the code-behind of your Items page. In the LoadState method, we will start the process of retrieving our data and binding it. We rely on some asynchronous calls to get data from REST, so we will need to put this data in another method and use the async keyword.

protected override void LoadState(Object navigationParameter, Dictionary<String, Object> pageState)
{
    // TODO: Assign a bindable collection of items to this.DefaultViewModel["Items"]
    BindData();
}
 
private async void BindData()
{
 
}

Before we start writing the method though, we need to include a few using statements.

using System.Net;
using System.Net.Http;
using System.Xml;
using System.Xml.Linq;

If you have looked at any of the other C# examples for working with the REST API, you will know they are heavily dependent on the HttpWebRequest object. However, with Windows Store Apps, we have to use HttpClient instead. We’ll start by defining our REST URL from up above.

string restUrl = "http://server/_api/lists/getbytitle('tasks')/items?$select=Title,DueDate,Body,Status,PercentComplete";

To handle authentication we first need to create an HttpClientHandler object. We want to automatically use the credentials of the currently logged in user so this is required. To enable this, just set UseDefaultCredentials to true. There are also other settings required which we’ll talk about below.

HttpClientHandler httpClientHandler = new HttpClientHandler();
httpClientHandler.UseDefaultCredentials = true;

We can now create the HttpClient object by passing the HttpClientHandler to the constructor.

HttpClient client = new HttpClient(httpClientHandler);

We then need to tell the REST API, that we want the result back as ATOM / XML as opposed to JSON. We do this by setting a few headers.

client.DefaultRequestHeaders.Add("Accept", "application/atom+xml");
client.DefaultRequestHeaders.Add("ContentType", "application/atom+xml;type=entry");

Now, we can send the request to SharePoint and wait for a response. We use the await keyword on the GetAsync() method which is why we needed the async keyword on the method signature. The EnsureSuccessStatusCode() method simply throws an exception if a valid 200 HTTP response is not received.

var response = await client.GetAsync(restUrl);
response.EnsureSuccessStatusCode();

At this point our data has been received back at the client from SharePoint. Now we need to begin the fun process of parsing it and binding it. We get the raw string XML data with the following method (also asynchronous). You could run the app at this point (with a few tweaks) if you wanted to see it in the debugger but we haven’t done anything wit the data yet.

string responseBody = await response.Content.ReadAsStringAsync();

Now we need to read the XML into an XDocument object so that we can use LINQ to XML to parse it.

StringReader reader = new StringReader(responseBody);
XDocument responseXml = XDocument.Load(reader, LoadOptions.None);

Now we have the data into something queryable. However, what we really need is a custom object that we can bind to. If you look back at the XML, you might have noticed a few namespaces in use in the XML document. We need to define those or our queries will never work.

XNamespace atom = "http://www.w3.org/2005/Atom";
XNamespace d = "http://schemas.microsoft.com/ado/2007/08/dataservices";
XNamespace m = "http://schemas.microsoft.com/ado/2007/08/dataservices/metadata";

Now, we can use LINQ to XML to select the data into a new anonymous type. If you look at the XML again, we want to query entry elements using the Descendants() method and then the actual values we want are inside the nested Content and then Properties elements. The data is heavily nested so it makes our LINQ to XML a little messy. It’s not too bad though. For the non-string values, I parse the data into the type that I want it (i.e.: DateTime).

var items = from item in responseXml.Descendants(atom + "entry")
            select new
            {
                Title = item.Element(atom + "content").Element(m + "properties").Element(d + "Title").Value,
                DueDate = DateTime.Parse(item.Element(atom + "content").Element(m + "properties").Element(d + "DueDate").Value),
                Status = item.Element(atom + "content").Element(m + "properties").Element(d + "Status").Value,
                PercentComplete = decimal.Parse(item.Element(atom + "content").Element(m + "properties").Element(d + "PercentComplete").Value)
            };

Now, we have data that can be bound to the GridView / ListView on the Items Page. To bind we assign our data source as follows:

this

.DefaultViewModel["Items"] = items;

Just like Windows Phone and SharePoint apps need to declare the capabilities of the application, Windows Store Apps are no different. To do this, open Package.appmanifest. In our case, we need to declare that we intend to communicate over the internal network (Private Networks) and that we need Enterprise Authentication. The latter allows the app to authenticate with the current user’s domain credentials automatically. If you don’t have this capability set, you are guaranteed a 401 Access Denied or Unable to connect to remote server error.

We can now run the app. However, there is one last thing we need to do. We need a way to navigate to the TaskItemsPage that we created. It loads MainPage by default. Without getting to deep into how Windows Store app navigation works, we’ll just throw a button on the MainPage and then navigate to the TaskItemsPage when clicked. You can drag and drop a button onto the MainPage using the designer. Double click on it and it will create the event handling method. Then we use Frame.Navigate() and pass it the type of page we want to go to, TaskItemsPage. Here is the code.

private void Button_Click_1(object sender, RoutedEventArgs e)
{
    Frame.Navigate(typeof(TasksItemsPage));
}

Run your app, and click on the button to navigate to your TaskItemsPage. If all goes well, you won’t receive any errors and you’ll see a page like the screen below. Note, that your application doesn’t currently have any way to exit. To get out you either need to Alt+Tab or move your mouse to the Top-Left corner of the screen to switch to the desktop.

This is great, but we’re not using all of our data yet. By default, it will bind the Title for us. However, we want to display some of our additional fields though. To do this, we can create a DataTemplate. We need to look into how it works first though. Locate the GridView in your XAML file. It should look something like this.

<GridView
    x:Name="itemGridView"
    AutomationProperties.AutomationId="ItemsGridView"
    AutomationProperties.Name="Items"
    TabIndex="1"
    Grid.RowSpan="2"
    Padding="116,136,116,46"
    ItemsSource="{Binding Source={StaticResource itemsViewSource}}"
    ItemTemplate="{StaticResource Standard250x250ItemTemplate}"
    SelectionMode="None"
    IsSwipeEnabled="false"/>

Notice the ItemTemplate and how it is bound to Standard250x250ItemTemplate. This template can actually be found in StandardStyles.xaml.

<DataTemplate x:Key="Standard250x250ItemTemplate">
    <Grid HorizontalAlignment="Left" Width="250" Height="250">
        <Border Background="{StaticResource ListViewItemPlaceholderBackgroundThemeBrush}">
            <Image Source="{Binding Image}" Stretch="UniformToFill" AutomationProperties.Name="{Binding Title}"/>
        </Border>
        <StackPanel VerticalAlignment="Bottom" Background="{StaticResource ListViewItemOverlayBackgroundThemeBrush}">
            <TextBlock Text="{Binding Title}" Foreground="{StaticResource ListViewItemOverlayForegroundThemeBrush}" Style="{StaticResource TitleTextStyle}" Height="60" Margin="15,0,15,0"/>
            <TextBlock Text="{Binding Subtitle}" Foreground="{StaticResource ListViewItemOverlaySecondaryForegroundThemeBrush}" Style="{StaticResource CaptionTextStyle}" TextWrapping="NoWrap" Margin="15,0,15,10"/>
        </StackPanel>
    </Grid>
</DataTemplate>

If you look at what it is binding, it’s looking for fields Image, Title, and Subtitle. We don’t have an image, so we can get rid of that. In its place, we’ll add the other fields in our dataset. We don’t want to edit the out-of-the-box template, so we can copy this snippet and add it to the Pages.Resources element in our TaskItemsPage.xaml. I then changed its name to TaskItemTemplate and added the remaining fields.

<DataTemplate x:Key="TaskItemTemplate">
    <Grid HorizontalAlignment="Left" Width="250" Height="250">
        <StackPanel VerticalAlignment="Top" Background="{StaticResource ListViewItemOverlayBackgroundThemeBrush}">
            <TextBlock Text="{Binding Title}" Foreground="{StaticResource ListViewItemOverlayForegroundThemeBrush}" Style="{StaticResource TitleTextStyle}" Height="60" Margin="15,0,15,0"/>
            <TextBlock Text="{Binding DueDate}" Foreground="{StaticResource ListViewItemOverlaySecondaryForegroundThemeBrush}" Style="{StaticResource CaptionTextStyle}" TextWrapping="NoWrap" Margin="15,0,15,10"/>
            <TextBlock Text="{Binding PercentComplete}" Foreground="{StaticResource ListViewItemOverlaySecondaryForegroundThemeBrush}" Style="{StaticResource CaptionTextStyle}" TextWrapping="NoWrap" Margin="15,0,15,10"/>
            <TextBlock Text="{Binding Status}" Foreground="{StaticResource ListViewItemOverlaySecondaryForegroundThemeBrush}" Style="{StaticResource CaptionTextStyle}" TextWrapping="NoWrap" Margin="15,0,15,10"/>
        </StackPanel>
    </Grid>
</DataTemplate>

Now we just need to change the template name in the GridView to use the TaskItemTemplate.

<GridView
    x:Name="itemGridView"
    AutomationProperties.AutomationId="ItemsGridView"
    AutomationProperties.Name="Items"
    TabIndex="1"
    Grid.RowSpan="2"
    Padding="116,136,116,46"
    ItemsSource="{Binding Source={StaticResource itemsViewSource}}"
    ItemTemplate="{StaticResource TaskItemTemplate}"
    SelectionMode="None"
    IsSwipeEnabled="false"/>

Run the app again and you’ll now have your custom fields bound. It should look something like this.

The DueDate and PercentComplete are not formatted in this case. I won’t cover that today, but if you look at the Blog Reader example, it explains the techniques you can use to do cool formatting. The Data Binding article goes into a lot of detail if you want to learn all of the ways you can bind data too. If you want a good tutorial to start from scratch on a Windows Store App, see the Hello, World example.

This turned out to be quite the long blog post. I hope you find it useful. If you find this interesting and you are going to be at SharePoint Conference 2012 in November (SPC12), you should be sure and attend my session Bringing SharePoint to the Desktop: Building Windows Store Apps with SharePoint 2013 (SPC025).

Follow me on twitter @coreyroth.

Getting Started with the Search REST API in SharePoint 2013 Preview

CoreyRoth — Fri, 07 Sep 2012 15:33:19 GMT

We have a brand new REST based API for interacting with Search in SharePoint 2013 Preview. Unfortunately, there is not a lot of information out there yet on how to interact with it. I have pieced together a couple of bits to help get you started. If you are looking to bring Search into an HTML / JavaScript based application, you’ll be able to get started right away. The first piece of the puzzle is putting together the right URL to access Search via REST. To do this, we start with the server name and append /_api/search/query. Just typing this into the browser will start giving you useful information. For example:

http://server/_api/search/query

If you look towards the bottom, you will see the Key SerializedQuery. This actually shows you the parameters passed into the request. It also provides you a hint as to what type of parameters you can pass to the REST interface. The one that might immediately stand out is QueryText. This is the actual search query. Think of it as the equivalent of what you type into the search box. There are a few other parameters that you can customize here as well such as the SummaryLength, MaxSnippetLength. and more. Let’s try adding QueryText to our URL and passing in a value.

http://server/_api/search/query?querytext=SharePoint

It turns out the value always has to be enclosed in single quotes (‘) like this:

http://server/_api/search/query?querytext=’SharePoint’

Now, we get some results:

The search results themselves are included in the d:RelevantResults element. It contains an element d:Table which has Bare with me as I am going to post the XML for one of the results so that we can inspect it further.

<d:element m:type="SP.SimpleDataRow">
  <d:Cells>
    <d:element m:type="SP.KeyValue">
      <d:Key>Rank</d:Key>
      <d:Value>20.268159866333</d:Value>
      <d:ValueType>Edm.Double</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>DocId</d:Key>
      <d:Value>31</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>WorkId</d:Key>
      <d:Value>31</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Title</d:Key>
      <d:Value>Getting the most out of SharePoint Search</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Author</d:Key>
      <d:Value>Corey Roth;SharePoint Setup</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Size</d:Key>
      <d:Value>2425342</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Path</d:Key>
      <d:Value>http://sp2010/Shared Documents/Getting the most out of SharePoint Search - SharePoint Saturday Denver.pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Description</d:Key>
      <d:Value>
        Template: Sam Moore; Silver Fox Productions, Inc.&#xD;
        Formatting:&#xD;
        Event Date: October 3-6th, 2011&#xD;
        Event Location: Anaheim, CA&#xD;
        Audience Type: Internal/External
      </d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Write</d:Key>
      <d:Value>2011-11-10T00:00:00.0000000</d:Value>
      <d:ValueType>Edm.DateTime</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>CollapsingStatus</d:Key>
      <d:Value>0</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>HitHighlightedSummary</d:Key>
      <d:Value xml:space="preserve">Passed all &lt;c0&gt;SharePoint&lt;/c0&gt; 2010 certification exams &lt;ddd/&gt; Introduce Search in &lt;c0&gt;SharePoint&lt;/c0&gt; Online &lt;ddd/&gt; The talk will be slides with quite a few demos of &lt;c0&gt;SharePoint&lt;/c0&gt; Online features &lt;ddd/&gt; </d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>HitHighlightedProperties</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>contentclass</d:Key>
      <d:Value>STS_ListItem_DocumentLibrary</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PictureThumbnailURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ServerRedirectedURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ServerRedirectedEmbedURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ServerRedirectedPreviewURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>FileExtension</d:Key>
      <d:Value>pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ContentTypeId</d:Key>
      <d:Value>0x010100B1CF83A7F86DFC468C975FFF33126DFD</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ParentLink</d:Key>
      <d:Value>http://sp2010/Shared Documents/Forms/AllItems.aspx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ViewsLifeTime</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ViewsRecent</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SectionNames</d:Key>
      <d:Value xml:space="preserve">Getting the most out of SharePoint Search&#xD;
;Getting the most out of SharePoint Search&#xD;
;Corey Roth&#xD;
About me&#xD;
;Key Theme&#xD;
;SharePoint is not aâ€¦&#xD;
;SharePoint is aâ€¦&#xD;
;Challenges with Search&#xD;
;Agenda&#xD;
;Key Takeaways&#xD;
;You have a choiceâ€¦&#xD;
;What can search index?&#xD;
;Search in SharePoint&#xD;
;Components of Search&#xD;
;Finding things easierâ€¦&#xD;
;Improve search with queries&#xD;
;Built-in Managed Properties&#xD;
;Segmenting results with Scopes&#xD;
;Querying Search and Scopes&#xD;
;Provide more search options&#xD;
;Many options for displaying scopes&#xD;
</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SectionIndexes</d:Key>
      <d:Value>1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SiteLogo</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SiteDescription</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>deeplinks</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>importance</d:Key>
      <d:Value>0</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SiteName</d:Key>
      <d:Value>http://sp2010</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>IsDocument</d:Key>
      <d:Value>true</d:Value>
      <d:ValueType>Edm.Boolean</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>LastModifiedTime</d:Key>
      <d:Value>2011-11-10T00:00:00.0000000</d:Value>
      <d:ValueType>Edm.DateTime</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>FileType</d:Key>
      <d:Value>pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>IsContainer</d:Key>
      <d:Value>false</d:Value>
      <d:ValueType>Edm.Boolean</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>WebTemplate</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>SecondaryFileExtension</d:Key>
      <d:Value>pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>OriginalPath</d:Key>
      <d:Value>http://sp2010/Shared Documents/Getting the most out of SharePoint Search - SharePoint Saturday Denver.pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>DisplayAuthor</d:Key>
      <d:Value>Corey Roth;SharePoint Setup</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Created</d:Key>
      <d:Value>2012-07-26T23:21:29.0000000</d:Value>
      <d:ValueType>Edm.DateTime</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PeopleInMedia</d:Key>
      <d:Value></d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>MediaDuration</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PictureWidth</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PictureHeight</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>DefaultEncodingURL</d:Key>
      <d:Value>http://sp2010/Shared%20Documents/Getting%20the%20most%20out%20of%20SharePoint%20Search%20-%20SharePoint%20Saturday%20Denver.pptx</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ExternalMediaURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>UserEncodingURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Community_MembersCount</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Community_RepliesCount</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Community_TopicsCount</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ReplyCount</d:Key>
      <d:Value>0</d:Value>
      <d:ValueType>Edm.Int64</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>LikesCount</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Discussion_BestAnswerID</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Discussion_Category</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Discussion_Post</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Discussion_LikesCount</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ListItemID</d:Key>
      <d:Value>6</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>FullPostBody</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PostAuthor</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>RootPostOwnerID</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>RootPostID</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>AttachmentType</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>AttachmentURI</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>MicroBlogType</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ModifiedBy</d:Key>
      <d:Value>
        Corey Roth
 
        SharePoint Setup
      </d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>RootPostUniqueID</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>Tags</d:Key>
      <d:Value></d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ImageDateCreated</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PictureURL</d:Key>
      <d:Value m:null="true" />
      <d:ValueType>Null</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ResultTypeIdList</d:Key>
      <d:Value>2;6</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>PartitionId</d:Key>
      <d:Value>0c37852b-34d0-418e-91c6-2ac25af4be5b</d:Value>
      <d:ValueType>Edm.Guid</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>UrlZone</d:Key>
      <d:Value>0</d:Value>
      <d:ValueType>Edm.Int32</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>AAMEnabledManagedProperties</d:Key>
      <d:Value>HierarchyUrl;OrgParentUrls;OrgUrls;OriginalPath;Path;recommendedfor;SitePath</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>ResultTypeId</d:Key>
      <d:Value>2</d:Value>
      <d:ValueType>Edm.Int32</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>RenderTemplateId</d:Key>
      <d:Value>~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_PowerPoint.js</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
    <d:element m:type="SP.KeyValue">
      <d:Key>piSearchResultId</d:Key>
      <d:Value>1_1</d:Value>
      <d:ValueType>Edm.String</d:ValueType>
    </d:element>
  </d:Cells>
</d:element>

As you can see, we now get a ton of information back from Search for a given search result. Let me point out some of the more interesting values. We have the usual values such as Title, Path, Author, Write (Modified Date), and HitHighlightedSummary. However, we also get a ton of new information. For images, you will get a PictureThumbnailUrl to allow you to easily show a thumbnail. This particular result is a PowerPoint and search understands the individual sections inside it now which you will see in SectionNames. SiteName provides the site hosting the item. Tags will provide any use of the Enterprise Keywords field. You also get a heap of social information about the item as well such as how many likes. Lastly, the RenderTemplateId tells you which template the result source is using to display it on the search results page. This is just one example, but you can see we get a lot of useful information about the search.

Looking at the XML in the browser is a great way to get familiar with what the API has to offer. When you are ready to start developing, it is very easy to take advantage of the REST API using JavaScript. You can do this with the $.ajax() method in jQuery and pass in the URL you used in the browser. You want to use the GET method and pass in a header telling it you want the results back as json. They have a good example of how this works on code.msdn.microsoft.com. Specifically, take a look at App.js in the example to see the code in action. It’s pretty simple.

If you want to take advantage of the REST API from C# or another .NET language, that is another story though. I haven’t been able to add a service reference for the REST API. All of the server side code examples I have seen call the REST API using HttpWebRequest which requires no less than 60 lines of code or so. I am hoping there is a better way but I haven’t seen one yet. If you have had better luck be sure and let me know.

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.