Editor’s note: Contributor Craig Pilkenton is a Senior Microsoft Consultant for Slalom Consulting.
In previous articles I’ve shown how to use SharePoint 2010’s REST interface for querying List data, as well as for creating a ‘Save My Searches‘ feature for your users. This article will cover the changes between how we used REST in 2010 and what we need to ‘update’ for using the streamlined interface in SharePoint 2013.
If you have gotten this far in the article then you’re probably actually curious as to what is different. The really big change that this article is going to cover is the new verbiage for making the GET request from your site; the new “/_api/” portion of the URL.
In SharePoint 2010, we would take the URL for our site and append "…/_vti_bin/listdata.svc". This initial call would then spit out ATOM XML data that showed all the Lists for that site.
**For bonus points, "vti" stood for Vermeer Technology Incorporated (the original creators of Front Page).
1) SharePoint 2010 REST overview
Now in 2013, we use a nomenclature that makes more sense, appending "…/_api/web/lists/" to our URL’s instead. This call still outputs the ATOM XML data of all the Lists, but instead of just List names we now receive many of the properties of the List just in case we need them, including the actual item count inside!
2) SharePoint 2013 REST overview
Once the target List name was found in the 2010 XML nodes we would copy the ‘compressed’ name (no spaces, or else!) and paste it to the end of the URL like so "…/_vti_bin/listdata.svc/Links", giving us an output of all the Items in that List, if any.
3) SharePoint 2010 List Items
Now in SharePoint 2013 we still copy the List name (no longer compressed) but instead of just appending it to the URL we need to paste it into the ‘getbytitle()’ function and add the "/items" flag to the end: "…/_api/web/lists/getbytitle(‘Calendar’)/items". This then outputs all the items in a List just as was available before.
4) SharePoint 2013 List Items
Switching back to 2010’s nomenclature, when one Item was found to focus on we’d copy the Id XML node and again add it to the end of the URL wrapped in parentheses "…/_vti_bin/listdata.svc/Links(2)". This would filter the results down to just one.
5) SharePoint 2010 Specific List Item
SharePoint 2013 keeps the same methodology for obtaining one item, again just pasting the Id XML node to the end of the URL, but after the ‘/items’ flag "…/_api/web/lists/getbytitle(‘Calendar’)/items(33)". The big difference in the ATOM output is we now receive more Item metadata including the full GUID of the Item along with if it has any attached items. This is extremely useful if you need to show a link to the attachment.
6) SharePoint 2013 Specific List Item
When only specific columns were needed or to filter large sets of results in SharePoint 2010, we’d utilize the QueryString Parameters allowed by the OData Query Options documentation "…/_vti_bin/listdata.svc/Contacts?$select=Id,FullName&$orderby=FullName" (see link below). This allows for only pulling back what is needed from the back-end where the cost is less to process.
7) SharePoint 2010 Selecting Item properties
With 2013, all of these awesome query operations are still available, the only change is the new URL syntax that precedes the OData Query Operations: "…/_api/web/lists/getbytitle(‘Calendar’)/items?$select=Id,Title, Description &$orderby=Title". The question mark starts the parameters section, the dollar sign prefixes the Query Options, and the ampersand splits different query options up.
8) SharePoint 2013 Selecting Item properties
One gotcha to note, the "$orderby=" will throw a ‘400 – Bad Request" error if used in a REST URL where you have specified a specific item to pull back "/_api/web/lists/getbytitle(‘Calendar’)/items(3)?$select=Id,Title,&$orderby=Title". A ‘$select’ will just politely be ignored.
9) SharePoint REST URI error
While the same core capabilities are there, and even expanded upon, the new convention is designed to make REST URI construction easier and to shorten the base path. Using _api abstract’s away the need to explicitly reference the client.svc web service, but SharePoint 2013 still recognizes and accepts URIs that reference the client.svc web service. This allows us to build our request links with a bit more characters since we still have the 255 character limit.
- Microsoft Developer Network: Get started with the SharePoint 2013 REST service
- Microsoft Developer Network: Use OData query operations in SharePoint REST requests
- Microsoft Developer Network: SharePoint 2013 REST API, endpoints, and samples
- OData.org: System Query Options