Editor’s note: Contributor Craig Pilkenton is a Senior Microsoft Consultant at CDW.
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.
<listName>" + listGuidCG + "</listName>
<FieldRef Name='FileRef' />
<FieldRef Name='DocIcon' />
<FieldRef Name='ContentType' />
<FieldRef Name='Document_x0020_Type' />
<FieldRef Name='LinkFilenameNoMenu' Ascending='True' />
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.
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
Here’s an example from NetFlix’s oData feed of their movie catalog. Note the QueryString variables and XML format of the data returned.
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.
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.
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).
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.
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.
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’