Sharepoint 2013 : Client-side Programming - Working with the REST API (part 1) - Understanding REST fundamentals

Remote Procedure Call (RPC) is a software architecture that uses a generated client-side proxy to communicate with a remote web service. Simple Object Access Protocol (SOAP) is the protocol that is used along with the RPC architecture in classic SharePoint web services. When developers think about making RPCs to SharePoint, they most often think about calling into a SOAP web service to perform tasks, such as retrieve user profile information, run a search, or interact with a list.

REST is a software architecture that uses uniform resource identifiers (URI) to specify operations against a remote service. Open Data Protocol (OData) is the protocol that is used along with REST to access many cloud-based services. Although SharePoint developers are most familiar with the RPC/SOAP approach, the REST/OData approach has become important when developing cloud-based solutions.

REST-based (known more commonly as “RESTful”) solutions use standard HTTP GET, POST, PUT, and DELETE verbs to perform CRUD operations against a remote source. Support for the standard HTTP verbs provides easy cross-platform data access and is ideally suited for cloud-based apps. The OData protocol returns results in either the Atom Publishing Protocol (AtomPub) or JSON.

SharePoint 2010 introduced support for RESTful access to list data through the listdata.svc web service. In SharePoint 2013, the listdata.svc service is still available, but it should not be used for any new development. Instead, the client.svc service has been expanded to include significant support for RESTful operations. Nearly all of the APIs available through CSOM have a corresponding RESTful endpoint. Additionally, the client.svc endpoint can be reached through the alias _api, which makes forming appropriate URIs more natural. Figure 1 presents a basic architectural diagram of the SharePoint 2013 REST infrastructure.

Figure 1. The REST interface supports RESTful calls made against the “underscore api” endpoint.

The essential task required to use the REST capabilities in SharePoint 2013 is to create the correct URI. One of the nice things about REST is that you can enter URIs directly in the browser and immediately see the result of the HTTP GET operation. By using this approach, you can experiment with the URIs quite easily to ensure that they return the desired results. For a SharePoint site collection located at wingtip.com, Example 1 shows the returned XML from the URI http://wingtip.com/_api/site, which returns the site collection properties.

<?xml version="1.0" encoding="utf-8" ?>
<entry xml:base="http://wingtip.com/_api/" xmlns="http://www.w3.org/2005/Atom"
 xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
 xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
 xmlns:georss="http://www.georss.org/georss"
 xmlns:gml="http://www.opengis.net/gml">
  <id>http://wingtip.com/_api/site</id>
  <category term="SP.Site" scheme="http://schemas.microsoft.com/ado/2007/08/
     dataservices/scheme" />
  <link rel="edit" href="site" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/
     EventReceivers" type="application/atom+xml;type=feed"
     title="EventReceivers" href="site/EventReceivers" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/
     Features" type="application/atom+xml;type=feed" title="Features" href="site/
     Features" />

  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Owner"
     type="application/atom+xml;type=entry" title="Owner" href="site/Owner" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/
     RecycleBin" type="application/atom+xml;type=feed"
     title="RecycleBin" href="site/RecycleBin" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/
     RootWeb" type="application/atom+xml;type=entry" title="RootWeb" href="site/
     RootWeb" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/
     UserCustomActions" type="application/atom+xml;type=feed"
     title="UserCustomActions" href="site/UserCustomActions" />
  <title />
  <updated>2012-08-27T12:14:20Z</updated>
   <author>
    <name />
  </author>
   <content type="application/xml">
     <m:properties>
      <d:AllowDesigner m:type="Edm.Boolean">true</d:AllowDesigner>
      <d:AllowMasterPageEditing m:type="Edm.Boolean">true
        </d:AllowMasterPageEditing>
      <d:AllowRevertFromTemplate m:type="Edm.Boolean">true
        </d:AllowRevertFromTemplate>
      <d:AllowSelfServiceUpgrade m:type="Edm.Boolean">true
        </d:AllowSelfServiceUpgrade>
      <d:AllowSelfServiceUpgradeEvaluation
        m:type="Edm.Boolean">true</d:AllowSelfServiceUpgradeEvaluation>
      <d:CompatibilityLevel m:type="Edm.Int32">15</d:CompatibilityLevel>
      <d:Id m:type="Edm.Guid">eb53c264-14db-4989-a395-b93cbe8b178c</d:Id>
      <d:LockIssue m:null="true" />
      <d:MaxItemsPerThrottledOperation m:type="Edm.Int32">5000
        </d:MaxItemsPerThrottledOperation>
      <d:PrimaryUri>http://wingtip.com/</d:PrimaryUri>
      <d:ReadOnly m:type="Edm.Boolean">false</d:ReadOnly>
      <d:ServerRelativeUrl>/</d:ServerRelativeUrl>
      <d:ShowUrlStructure m:type="Edm.Boolean">true</d:ShowUrlStructure>
      <d:UIVersionConfigurationEnabled
        m:type="Edm.Boolean">false</d:UIVersionConfigurationEnabled>
      <d:UpgradeReminderDate m:type="Edm.DateTime">1899-12-30T00:00:00
        </d:UpgradeReminderDate>
      <d:Url>http://wingtip.com</d:Url>
    </m:properties>
  </content>
</entry>

The main entry point for RESTful URIs is through the _api endpoint, which is referenced through either the site collection or site. Using the site collection or site URI as the root establishes the context for the RESTful operation. The following code shows a typical entry point:

http://wingtip.com/_api

Following the root reference is the namespace, which refers to the workload that you want to reference, such as search or taxonomy. Table 1 shows some sample namespaces in URIs. If the functionality you are invoking resides in SharePoint foundation, no namespace is required. If the functionality resides in one of the many other available namespaces, it can be difficult to determine the exact URI without some form of documentation.

The namespace in the URI is followed by a reference to the object, property, indexer, or method target that you want to invoke. Objects can include site collections, sites, lists, and list items. After an object is referenced, you can go on to reference the properties, indexers, and methods of the object. Table 2 shows several sample URIs referencing objects, properties, indexers, and methods.

The RESTful URI ends with any OData query operators to specify selecting, sorting, or filtering. The $select operator is used to specify what fields to return from the query of a collection such as list items or fields. The $order operator specifies the sort order of the results. In general, if you do not provide a $select operator in your URI, all items in the collection are returned, with the exception of any field or property that might be particularly large. The $select operator also supports returning projected fields from related lookup lists by using the $expand operator. Table 3 shows several sample URIs selecting items to return.

You use the $filter operator to filter the results of the RESTful operation. The RESTful URI can include numeric comparisons, string comparisons, and date/time functions. Table 4 shows sample URIs that filter returned collections.

The $top and $skip operators are used to implement paging for results. The $top operator specifies how many results to return. You can use the $skip operator to pass over a given number of items. Table 5 lists several examples using these operators.