Navigate Up
Sign In
Supporters of Developer
Web

Got REST? Querying SharePoint List data using REST services client-side: Part 1

Item is currently unrated. Press SHIFT+ENTER to rate this item.1 star selected. Press SHIFT+ENTER to submit. Press TAB to increase rating. Press SHIFT+ESCAPE to leave rating submit mode.2 stars selected. Press SHIFT+ENTER to submit. Press TAB to increase rating. Press SHIFT+TAB to decrease rating. Press SHIFT+ESCAPE to leave rating submit mode.3 stars selected. Press SHIFT+ENTER to submit. Press TAB to increase rating. Press SHIFT+TAB to decrease rating. Press SHIFT+ESCAPE to leave rating submit mode.4 stars selected. Press SHIFT+ENTER to submit. Press TAB to increase rating. Press SHIFT+TAB to decrease rating. Press SHIFT+ESCAPE to leave rating submit mode.5 stars selected. Press SHIFT+ENTER to submit. Press SHIFT+TAB to decrease rating. Press SHIFT+ESCAPE to leave rating submit mode.

 

Editor's note: Contributor Craig Pilkenton is a Senior Microsoft Consultant at CDW.

So you need to get some data out of SharePoint, show it to your users in a non-utilitarian way, but don't have time to build a full .NET Web Part? Find a List DataView too limiting and XSLT too painful? SharePoint (with JavaScript/jQuery) has your back.

Since SharePoint 2003 we have always had client-side ASP.NET Web Services we can query to pull List data out to show as we wish (http://Server04:50000/Examples/_vti_bin/Lists.asmx), but no matter the query language we used, you've always had to create and receive SOAP (Simple Object Access Protocol) packets using XML-based CAML (Collaborative Application Markup Language) over the wire.

Below is just a simple example of a packet we would need to send to SharePoint after ensuring its validity using a 3rd party toolset. If the CAML query is wrong SharePoint will only return a vague CAML error.

<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'>
	<soapenv:Body>
		 <GetListItems xmlns='http://schemas.microsoft.com/sharepoint/soap/'>
			<listName>" + listGuidCG + "</listName>
			<viewFields><ViewFields>
			   <FieldRef Name='FileRef' />
			   <FieldRef Name='DocIcon' />
			   <FieldRef Name='ContentType' />
			   <FieldRef Name='Document_x0020_Type' />
			</ViewFields></viewFields>
			<query>
				<Query>
					<OrderBy>
						<FieldRef Name='LinkFilenameNoMenu' Ascending='True' />
					</OrderBy>
				</Query>
			</query>
			<queryOptions>
				<QueryOptions>
					<RowLimit>150</RowLimit>
					<IncludeMandatoryColumns>FALSE</IncludeMandatoryColumns>
					<DateInUtc>TRUE</DateInUtc>
				</QueryOptions>
			</queryOptions>
		</GetListItems>
	</soapenv:Body>
</soapenv:Envelope>

Looks like fun, huh? I thought not, and that's just the initial POST request!

To make querying easier, Microsoft implemented REST (Representational State Transfer plus HTTP) into the SharePoint 2010 platform using ADO.NET Data Services to make client-side data retrieval easier and more lightweight. What is REST, you ask? It is the Web itself as it was originally intentioned, a client either in transition between application states or "at rest“, able to interact with its user, but creates no load and consumes no per-client storage. It is also security-trimmed just like everything else in the SharePoint platform.

So what does that really mean? It is simply SharePoint data, or any oData-compliant (Open Data Protocol) information, output to the client like an RSS feed.

2011-12-27-GotRest-01.png

Note: if you are not seeing the SharePoint List information as XML in the browser then you'll need to turn off RSS feed reading. In Internet Explorer 7 or greater, go to Tools-->Internet Options-->Content tab-->Feeds and Web Slices-settings

2011-12-27-GotRest-02.png

Here's an example from NetFlix's oData feed of their movie catalog. Note the QueryString variables and XML format of the data returned.
http://odata.netflix.com/Catalog/Titles?$top=10&$orderby=ReleaseYear desc

2011-12-27-GotRest-03.png

Well that looks pretty simple, doesn't it? We can just view it in any current browser without any custom tools. So how do we access it? For SharePoint 2010, we change our Site URL to access the always-on service.
http://Server04:50000/Examples/_vti_bin/ListData.svc

2011-12-27-GotRest-04.png

So what are we seeing here? By loading that Site URL with the service extension we are automatically calling SharePoint's REST service for that specific site (without a SOAP packet) and receiving a quick, light-weight output of all the Lists for that site with little effort.

Note: interacting with the REST service is case-sensitive for the List name and the QueryString variables. If you aren't receiving any data back, check your values for typos as this is the ‘error screen’ you will see.

2011-12-27-GotRest-05.png

Now we'll target a specific List by copying the name of our target List from the page (to avoid typos) and appending it to our URL, telling the REST service to 'target' that list for output. This will then show details of the List itself and all the entries we've previously entered (10 in my example).
http://Server04:50000/Examples/_vti_bin/ListData.svc/EmployeeDirectory

2011-12-27-GotRest-06.png

That's great and all, but your users probably want to see only a subset of the records, maybe even with a filter. Using the ADO.NET Data Services guide (search for 'Structure of Web Data Services URLs'), we'll begin passing some QueryString variables against the List. The primary ones you will probably use are $orderby, $top, and $filter with some Logical Operators.

Note: Interacting with the QueryString requires putting a '?' before the first variable passed and '&' before each subsequent variable after that.

Let's first only pull the top 2 of the records back as that's what the business is looking for.
http://Server04:50000/Examples/_vti_bin/ListData.svc/EmployeeDirectory?$top=2

2011-12-27-GotRest-07.png

That's good, but we forgot to sort by anything to control which records are returned. We'll now add an order by clause to correct that.
http://Server04:50000/Examples/_vti_bin/ListData.svc/EmployeeDirectory?$top=2&$orderby=Modified desc

2011-12-27-GotRest-08.png

And finally the business decided they don't need to see certain individuals, in this case Inactive Status, so we'll filter by that.
http://Server04:50000/Examples/_vti_bin/ListData.svc/EmployeeDirectory?$top=2&$orderby=Modified desc&$filter=StatusValue eq 'Active'

2011-12-27-GotRest-09.png

And that's all that's needed to get the data back, with all the 'data source debugging' done in the browser. In the next part of this series, we'll take our querying of the SharePoint data to the next level and begin consuming it with JavaScript/jQuery to display on a Site for our users.

Categories: Javascript and jQuery; CAML; XSLT; MOSS; WSS; 2007; 2010

Comments

Christophe

A heavy response

For the record, there's another method that doesn't require CAML and has been around since SP 2003: owssvr.dll. Of course it doesn't offer all the capabilities of REST, just simple filtering.
 
What bothers me with the REST service is the size of the response. I just posted a question about this, would you have any suggestion?

Posted 29-Dec-2011 by Christophe
kams

Time Savior

Thanks so much for posting such a nice tip for turning off the RSS feed.Its really helped me.

Posted 14-May-2013 by kams
kams

nice post

Rss feeding tip worked.Tks

Posted 14-May-2013 by kams

Notify me of comments to this article

E-mail:
   

Add Comment

Title:

 
Comment:
Email:

   


Name:

 
Url: