Using the updated SharePoint 2013 REST API versus the SharePoint 2010 model


You may also be interested in: Simple SharePoint Migration Tool – Content Matrix by Metalogix


 

Editor’s note: Contributor Craig Pilkenton is a Senior Microsoft Consultant for Slalom Consulting.

Overview Summary

Since SharePoint 2010, the platform has had REST URI services (Representational State Transfer) that are comparable to the existing SharePoint client object models. This meant that we could interact remotely with SharePoint data by using any technology that supports REST web requests (usually JavaScript) to perform Create, Read, Update, and Delete (CRUD) operations from our apps, allowing us to create applications that consume SharePoint data without pushing managed code into our Farms.

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.

Body

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).

2013-10-08-SharePoint2013RESTAPI-01.jpg
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!

2013-10-08-SharePoint2013RESTAPI-02.jpg
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.

2013-10-08-SharePoint2013RESTAPI-03.jpg
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.

2013-10-08-SharePoint2013RESTAPI-04.jpg
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.

2013-10-08-SharePoint2013RESTAPI-05.jpg
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.

2013-10-08-SharePoint2013RESTAPI-06.jpg
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.

2013-10-08-SharePoint2013RESTAPI-07.jpg
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.

2013-10-08-SharePoint2013RESTAPI-08.jpg
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.

2013-10-08-SharePoint2013RESTAPI-09.jpg
9) SharePoint REST URI error

Final Summary

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.

Reference Links