Logo
programming4us
programming4us
programming4us
programming4us
Home
programming4us
XP
programming4us
Windows Vista
programming4us
Windows 7
programming4us
Windows Azure
programming4us
Windows Server
programming4us
Windows Phone
 
Windows Server

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

- Free product key for windows 10
- Free Product Key for Microsoft office 365
- Malwarebytes Premium 3.7.1 Serial Keys (LifeTime) 2019
11/15/2014 2:56:08 AM

If you are planning to create apps that are based primarily on JavaScript, you will be interested in the Representational State Transfer (REST) API. Making REST calls from JavaScript is considerably easier than making the equivalent CSOM calls. Furthermore, several libraries such as jQuery provide additional support for REST calls. All of this makes the REST API an attractive approach for app development.

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.

The REST interface supports RESTful calls made against the “underscore api” endpoint.
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.

Example 1. 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.

Table 1. Namespace sample URIs

Sample URI

Description

http://wingtip.com/_api/

SharePoint foundation namespace

http://wingtip.com/_api/search

Enterprise search namespace

http://wingtip.com/_api/sp.userProfiles.peopleManager

User profiles namespace

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.

Table 2. Object sample URIs

Sample URI

Description

http://wingtip.com/_api/site

Site collection object

http://wingtip.com/_api/web

Site object

http://wingtip.com/_api/site/url

Site collection url property

http://wingtip.com/_api/web/lists

Site lists collection

http://wingtip.com/_api/web/lists(‘25e2737d-f23a-4fdb-ad5a-e5a94672504b’)

Site lists collection indexer

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)

Site lists collection method

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items

List items collection

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.

Table 3. Selecting and sorting items

Sample URI

Description

http://wingtip.com/_api/web/lists/getbytitle(‘Modules’)/items Select all fields in Modules list.

 

http://wingtip.com/_api/web/lists/getbytitle(‘Modules’)/items? $select=Title

Select Title field in Modules list.

http://wingtip.com/_api/web/lists/getbytitle(‘Modules’)/items? $select=Title,Instructor/FullName&$expand=Instructor/FullName

Select the Title and Instructor fields from the Modules list. The Instructor field is a lookup from another list, so expand the selection to include the FullName field from the list used as a lookup.

http://wingtip.com/_api/web/lists/getbytitle(‘Modules’)/items? $select=Title&$order=Modified

Select Title field in Modules list and sort by the modified date.

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.

Table 4. Filtering items

Sample URI

Description

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items?$filter=FirstName eq ‘Brian’

Return the item from the Contacts list for which the FirstName is equal to “Brian”

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items?$filter=startswith(FirstName,‘B’)

Return all items from the Contacts list for which the first name starts with the letter B

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items? $filter=month(Modified) eq 8

Return all items from the Contacts list modified in August

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.

Table 5. Paging items

Sample URI

Description

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items?$top=10

Returnthe the first 10 items in the Contacts list

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/items?$top=10&$skip=10

Returns the second page of results, with 10 results on each page

http://wingtip.com/_api/web/lists/getbytitle(‘Contacts’)/ items?$sort=Title&$top=10&$skip=10

Returns the second page of results, sorted by Last Name

Other -----------------
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 7)
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 6)
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 5) - Moving Mailboxes
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 4) - Installing Exchange Server 2007 on a Server System
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 3) - Installing Exchange Server 2007 Prerequisites
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 2)
- Migrating to Exchange Server 2007 : Migrating from Exchange 2000 Server or Exchange Server 2003 to Exchange Server 2007 (part 1) - Planning Your Migration
- Migrating to Exchange Server 2007 : Deploying a Prototype Lab for the Exchange Server 2007 Migration Process
- Migrating to Exchange Server 2007 : Moving to Native Mode in Exchange
- Migrating to Exchange Server 2007 : Understanding What’s New and What’s Different with Exchange Server 2007
 
 
Top 10
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 2) - Wireframes,Legends
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Finding containers and lists in Visio (part 1) - Swimlanes
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Formatting and sizing lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Adding shapes to lists
- Microsoft Visio 2013 : Adding Structure to Your Diagrams - Sizing containers
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 3) - The Other Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 2) - The Data Properties of a Control
- Microsoft Access 2010 : Control Properties and Why to Use Them (part 1) - The Format Properties of a Control
- Microsoft Access 2010 : Form Properties and Why Should You Use Them - Working with the Properties Window
- Microsoft Visio 2013 : Using the Organization Chart Wizard with new data
 
programming4us
Windows Vista
programming4us
Windows 7
programming4us
Windows Azure
programming4us
Windows Server