SharePoint 2013 REST API & Remote Authentication

SharePoint 2013 REST API
& Remote Authentication
Overview and Samples - consolidated from various internet resources
Adil Ansari – SharePointConsultant,Lastupdatedon:
6/10/2015

Contents
Overview ...........................................................................................................................................2
References:....................................................................................................................................2
Use HTTP commandswith the SharePoint 2013 REST service ................................................................2
SharePoint REST endpointsexample....................................................................................................3
Construct REST URLs to access SharePoint resources............................................................................4
Advanced Operations......................................................................................................................5
Search API..........................................................................................................................................8
GET requests.............................................................................................................................8
POST requests...........................................................................................................................8
Suggest request........................................................................................................................9
Search Sytanx.................................................................................................................................9
- QueryText parameter.........................................................................................................9
- SourceId.............................................................................................................................9
- RowLimit..........................................................................................................................10
- StartRow ..........................................................................................................................10
- RowsPerPage...................................................................................................................10
- Refiners............................................................................................................................11
- RefinementFilters.............................................................................................................11
- SortList.............................................................................................................................12
Search Examples...........................................................................................................................12
Authentication(Contentsubjecttochange as the authenticationmechanismformobile appisnotyet
decided)...........................................................................................................................................14
Batch Job Support.............................................................................................................................16
Debugging........................................................................................................................................17

Overview
SharePoint 2013 introduces a Representational State Transfer (REST) service that is comparable to
the existing SharePoint client object models. Now, developers can interact remotely with SharePoint
data by using any technology that supports REST web requests. This means that developers can
perform Create, Read, Update, and Delete (CRUD) operations from their apps for SharePoint,
solutions, and client applications, using REST web technologies and standard Open Data Protocol
(OData) syntax.
References:
https://msdn.microsoft.com/en-us/library/jj163876.aspx
https://msdn.microsoft.com/EN-US/library/dn194079.aspx
Use HTTP commands with the SharePoint 2013 RESTservice
To use the REST capabilities that are built into SharePoint 2013, you construct a RESTful HTTP
request, using the OData standard, which corresponds to the client object model API you want to
use. The client.svc web service handles the HTTP request and serves the appropriate response in
either Atom or JavaScript Object Notation (JSON) format. The client application must then parse that
response.
The endpoints in the SharePoint 2013 REST service correspond to the types and members in the
SharePoint client object models. By using HTTP requests, you can use these REST endpoints to
perform typical CRUD operations against SharePoint entities, such as lists and sites.
In general:
Operations HTTP Request Keep in mind
Read a
resource
GET
Create or
update a
resource
POST Use POST to create entities such as lists and sites. The SharePoint 2013
REST service supports sending POST commands that include object
definitions to endpoints that represent collections.
For POST operations, any properties that are not required are set to their
default values. If you attempt to set a read-only property as part of
a POST operation, the service returns an exception.
Update or
insert a
resource
PUT Use PUT and MERGE operations to update existing SharePoint objects.
Any service endpoint that represents an object property set operation
supports both PUT requests and MERGE requests.
 For MERGE requests, setting properties is optional; any properties that
you do not explicitly set retain their current property.
 For PUT requests, if you do not specify all required properties in object
updates, the REST service returns an exception. In addition, any optional
properties you do not explicitly set are set to their default properties.
Delete a
resource
DELETE Use the HTTP DELETE command against the specific endpoint URL to
delete the SharePoint object represented by that endpoint.

In the case of recyclable objects, such as lists, files, and list items, this
results in a Recycle operation.
SharePoint RESTendpoints example
The following table contains typical REST endpoint URL examples to get you started working with
SharePoint data. Prepend http://server/site/_api/ to the URL fragments shown in the table to
construct a fully qualified REST URL. Where necessary for POST commands, the table contains
sample data you must pass in the HTTP request body to create the specified SharePoint item. Items
in italics represent variables that you must replace with your values.
Description URL endpoint HTTP
method
Body content
Retrieves the title of
a list
web/title GET Not applicable
Retrieves all lists on a
site
lists GET Not applicable
Retrieves a single
'list's metadata
lists/getbytitle('listname') GET Not applicable
Retrieves items
within a list
lists/getbytitle('listname')/i
tems
GET Not applicable
Retrieves a specific
property of a
document. (In this
case, the document
title.)
lists/getbytitle('listname')?
select=Title
GET Not applicable
Creates a list lists POST {
'_metadata':{'type':SP.List},
'AllowContentTypes': true,
'BaseTemplate': 104,
'ContentTypesEnabled': true,
'Description': 'My list description',
'Title': 'RestTest'
}
Adds an item to a list lists/getbytitle('listname')/i
tems
POST {
'_metadata':{'type':SP. listnameListItem},
'Title': 'MyItem'
}

Construct RESTURLs to access SharePoint resources
Whenever possible, the URI for these REST endpoints closely mimics the API signature of the
resource in the SharePoint client object model. The main entry points for the REST service represent
the site collection and site of the specified context.
To access a specific site collection, use the following construction:
http://server/site/_api/site
To access a specific site, use the following construction:
http://server/site/_api/web
The SharePoint REST service is implemented in a client.svc file in the virtual folder /_vti_bin on the
SharePoint Web site, but SharePoint 2013 supports the abbreviation “_api” as a substitute for
“_vti_bin/client.svc.” This is the base URL for every endpoint:
http://<domain>/<site url>/_api/
The service-relative URLs of specific endpoints are appended to this base; for example, you can
retrieve the lists from a SharePoint site with this URL:
http://<domain>/<site url>/_api/web/lists
You can get a reference to a particular list by specifying its ID or, as in the following example, by its
title:
_api/web/lists/getByTitle('samplelist')/
The “web” in these examples is not a placeholder—it’s the name of an object of the Web class in the
SharePoint client object model; “lists” is the name of a collection property and “getByTitle” is a
method of that collection object. This paradigm enables Microsoft to combine the API reference for
the endpoints and the JavaScript object model; for examples, see SP.Web.lists and
SP.ListCollection.getByTitle at bit.ly/14a38wZand bit.ly/WNtRMO, respectively. Also, the syntax
roughly mirrors the structure of a SharePoint tenancy. You get information about a site collection at
_api/site; information about a SharePoint Web site at _api/web; and information about all of the lists
in a Web site at _api/web/lists. The last URL delivers a list collection that consists of all the lists on the
SharePoint site. You can also take a look at how these objects are represented in XML by navigating
to those URLs on your development site collection.
By default, the data is returned as XML in AtomPub format as extended by the OData format, but
you can retrieve the data in JSON format by adding the following accept header to the HTTP request:
accept: application/json;odata=verbose
Whether to use JSON or Atom (XML) depends on your skill set, the programming platform you’re
using and whether network latency will be an issue for your app. JSON uses far fewer characters, so it
makes sense for smaller payloads over the network. On the other hand, most major platforms,
including the Microsoft .NET Framework, have rich XML-parsing libraries.

We’ll describe later how you can use OData query operators to select, filter and order the data.
Writing to SharePoint: When you write to SharePoint, your requests use the POST verb—though in
some cases you’ll override this verb by adding an X-HTTP-Method header to the request and
specifying a value of PUT, MERGE or DELETE. In general, POST is used when you’re creating an object
such as a site, list or list item. MERGE is used when you’re updating certain properties of an object
and you want the other properties to keep their current values. PUT is used when you want to
replace an item; properties not specifically mentioned in the request are set to their default values.
DELETE is used when you want to remove an item.
Every request that writes to SharePoint must include a form digest. Your code gets the digest as part
of a set of information returned by the following endpoint:
_api/contextinfo
You must use the POST verb in this request (with an empty body) and include the Authorization
header as described earlier. In some frameworks you’ll have to specify that the length of the POST
request is 0. In the structure that’s returned there’s a property named FormDigestValue that contains
the form digest. In all subsequent POST requests, you add an X-RequestDigest header with the
digest as its value.
Note that if you’re working with a SharePoint-hosted app and a page that uses the default master
page for SharePoint, the digest is already on the page in an element with the ID “__REQUESTDIGEST”
(with two underscore characters). So, instead of calling the contextinfo endpoint, you can simply read
the value with script such as this jQuery code:
var formDigestValue = $("__REQUESTDIGEST").val()
Of course, you need to add to the body of the request the data you want to write, or an
identification of the data you want to delete. You can use either AtomPub/OData format or JSON
format. If you choose the latter, you must add a content-type header to the request like the
following:
content-type: application/json;odata=verbose
For a full set of concrete examples of Create, Read, Update and Delete (CRUD) operations on
SharePoint objects, see “How to: Complete basic operations using SharePoint 2013 REST endpoints”
at bit.ly/13fjqFn.
Advanced Operations
A certain degree of complexity comes along with the power of the SharePoint 2013 REST interface.
The interface supports operations for sorting, filtering and ordering the data that it returns. It also
supports a large number of SharePoint-specific operations. These additional capabilities add features
and benefits that you don’t always see in a standard REST implementation. The next sections discuss
some of the most important factors you’ll encounter when working with REST and SharePoint.
Filtering, Selecting and Sorting You can use OData system query options to control what data is
returned and how it’s sorted. Figure 2 shows the supported options.
Figure 2 Options for Filtering and Sorting Data

Option Purpose
$select Specifies which fields are included in the returned data.
$filter Specifies which members of a collection, such as the items in a list, are returned.
$expand Specifies which projected fields from a joined list are returned.
$top Returns only the first n items of a collection or list.
$skip Skips the first n items of a collection or list and returns the rest.
$orderby Specifies the field that’s used to sort the data before it’s returned.
To return the author, title and ISBN from a list called Books, for example, you’d use the following:
_api/web/lists/getByTitle('Books')/items?$select=Author,Title,ISBN
If the $select option isn’t used, all fields are returned except fields that would be resource-intensive
for the server to return. If you need these fields, you need to use the $select option and specify them
by name. To get all fields, use $select=‘*’.
To get all the books by Mark Twain, use:
_api/web/lists/getByTitle('Books')/items?$filter=Author eq 'Mark Twain'
For a list of all the operators supported for the $filter option, see the MSDN Library article,
“Programming using the SharePoint 2013 REST service,” at bit.ly/Zlqf3e.
To sort the books by title in ascending order, use:
_api/web/lists/getByTitle('Books')/items?$orderby=Title asc
Use “desc” in place of “asc” to specify descending order. To sort by multiple fields, specify a comma-
separated list of fields.
You can conjoin multiple options using the “&” operator. To get only the Title of the first two books
by Mark Twain, use:
_api/web/lists/getByTitle('Books')/items?$select=Title&$filter=Author eq 'Mark
Twain'&$top=2
The service will completely resolve each option before it applies the next one. So each option only
applies to the data set that’s produced by the options to its left in the URL. Thus, the order in which
you apply the options matters. For example, the following URL returns items 3-10:
_api/web/lists/getByTitle('Books')/items?$top=10&$skip=2
But reversing the two options returns items 3-12:
_api/web/lists/getByTitle('Books')/items?$skip=2&$top=10
You can get the bottom n items by using a descending $orderby and a $top option (in that order).
The following URL gets the bottom two items:

_api/web/lists/getByTitle('Books')/items?$orderby=ID desc&$top=2
When a SharePoint list has a lookup field to another list, this effectively serves as a join of the two
lists. You can use the $expand option to return projected fields from the joined list. For example, if
the Books list has a PublishedBy field that looks up to the Name field of a Publisher list, you can
return those names with this URL:
_api/web/lists/getByTitle('Books')/items?$select=Title,PublishedBy/Name&$expand=Publishe
dBy
Notice that you reference the column in the foreign list by using the syntax
lookup_column_display_name/foreign_column_name, not foreign_list_name/foreign_column_name.
It’s also important to note that you can’t select a lookup field name without also expanding it.

SearchAPI
Search in SharePoint 2013 includes a Search REST service you can use to add search functionality to
your client and mobile applications by using any technology that supports REST web requests. You
can use the Search REST service to submit Keyword Query Language (KQL) or FAST Query Language
(FQL) queries in your apps for SharePoint, remote client applications, mobile applications, and other
applications.
The Search REST service supports both HTTP POST and HTTP GET requests.
GET requests
Construct the URI for query GET requests to the Search REST service as follows:
/_api/search/query
For GET requests, you specify the query parameters in the URL. You can construct the GET request
URL in two ways:
http://server/_api/search/query?query_parameter=value&query_parameter=value
http://server/_api/search/query(query_parameter=value&query_parameter=<value>)
POST requests
You construct the URI for query POST requests to the Search REST service as follows:
/_api/search/postquery
For POST requests, you pass the query parameters in the request in JavaScript Object Notation
(JSON) format.
The HTTP POST version of the Search REST service supports all parameters supported by the
HTTP GET version. However, some of the parameters have different data types, as described in below
table.
Parameter Data type
SelectProperties string[]
RefinementFilters string[]
SortList Sort
HithighlightedProperties string[]
Properties Microsoft.SharePoint.Client.Search.Query.KeywordQueryProperties
Use POST requests in the following scenarios:
 When you'll exceed the URL length restriction with a GET request.
 When you can't specify the query parameters in a simple URL. For example, if you have to
pass parameter values that contain a complex type array, or comma-separated strings, you
have more flexibility when constructing the POST request.
 When you use the ReorderingRules parameter because it is supported only
with POST requests.

Suggest request
The Search REST service includes a Suggest endpoint you can use in any technology that supports
REST web requests to retrieve query suggestions that the search system generates for a query from
client or mobile applications.
The URI for GET requests to the Search REST service’s Suggest endpoint is:
/_api/search/suggest
The query suggestion parameters are specified in the URL. You can construct the request URL in two
ways:
http://server/_api/search/suggest?parameter=value&parameter=value
http://server/_api/search/suggest(parameter=value&parameter=value)
Search Sytanx
The following sections describe the query parameters you can use to submit search queries with the
Search REST service.
- QueryText parameter
A string that contains the text for the search query.
GET request
http://server/_api/search/query?querytext='sharepoint'
POST request data
{
'__metadata' : {'type' :
'Microsoft.Office.Server.Search.REST.SearchRequest'},
'Querytext' : 'sharepoint'
}
- SourceId
The result source ID to use for executing the search query. Use source ID as ‘b9a7990-05ea-4af9-
81ef-edfab16c4e31’ to do the people search.
GET request
http://server/_api/search/query?querytext='sharepoint'&sourceid='8413cd39-2156-4e00-b54d-
11efd9abdb89'
POST request data
{

'Querytext' : 'sharepoint',
'SourceId' : '8413cd39-2156-4e00-b54d-11efd9abdb89'
}
- RowLimit
The maximum number of rows overall that are returned in the search results. Compared to
RowsPerPage, RowLimit is the maximum number of rows returned overall.
GET request
http://server/_api/search/query?querytext='sharepoint'&rowlimit=30
POST request data
{
'RowLimit' : '30'
}
- StartRow
The first row that is included in the search results that are returned. You use this parameter when you
want to implement paging for search results.
GET request
http://server/_api/search/query?querytext='sharepoint'&startrow=10
POST request data
{
'StartRow' : '10'
}
- RowsPerPage
The maximum number of rows to return per page. Compared to RowLimit, RowsPerPage refers to
the maximum number of rows to return per page, and is used primarily when you want to implement
paging for search results.

GET request
http://server/_api/search/query?querytext='sharepoint'&rowsperpage=10
POST request data
{
'RowsPerPage' : '10'
}
- Refiners
The set of refiners to return in a search result.
GET request
http://server/_api/search/query?querytext='sharepoint'&refiners='author,size'
POST request data
{
'__metadata':{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'},
'Querytext':'sharepoint',
'Refiners': {
'results' : ['author,size']
}
}
- RefinementFilters
The set of refinement filters used when issuing a refinement query. For GET requests, the
RefinementFilters parameter is specified as an FQL filter. For POST requests, the RefinementFilters
parameter is specified as an array of FQL filters.
GET request
http://server/_api/search/query?querytext='sharepoint'&refinementfilters='fileExtension:equals("docx
")'
POST request data
{
'RefinementFilters' : {

'results' : ['fileExtension:equals("docx")']
}
}
- SortList
The list of properties by which the search results are ordered.
GET request
http://server/_api/search/query?querytext='sharepoint'&sortlist='rank:descending,modifiedby:ascend
ing'
POST request data
{
'__metadata' :
{'type':'Microsoft.Office.Server.Search.REST.SearchRequest'},
'SortList' :
{
'results' : [
{
'Property':'Created',
'Direction': '0'
},
{
'Property':'FileExtension',
'Direction': '1'
}
]
}
}
Search Examples
SharePoint 2013 REST Search API:
http://zimmergren.net/technical/sp-2013-searching-in-sharepoint-2013-using-the-rest-new-apis
SharePoint 2013 REST People Search:
http://www.c-sharpcorner.com/UploadFile/sagarp/how-to-search-for-people-as-a-search-scope-
content-source/

SharePoint 2013 REST Search API with various operators
http://www.onemenny.com/blog/sharepoint-2013-rest-api-search-service/
SharePoint 2013 REST Search API with paging:
http://www.sharepointempower.com/Blog/Post/15/Paging-using-SharePoint-2013-REST-API
Helpful tools for debugging the REST Search API request and response:
https://sp2013searchtool.codeplex.com/

Authentication (Content subject to change as the authentication
mechanism for mobile app is not yet decided)
There are two scenarios for the remote mobile authentications:
1. Below figure shows the sequence of steps for smart clients when the issuer is ADFS authenticating
users against Active Directory.
Reference: https://msdn.microsoft.com/en-us/library/ff359108.aspx

Examples/Samples:
Remote device authentication with SharePoint using the SAML Token
http://leandrob.com/2012/02/request-a-token-from-adfs-using-ws-trust-from-ios-objective-c-iphone-
ipad-android-java-node-js-or-any-platform-or-language/
One more example but in this case SharePoint Online is being used, so the SOAP request might be
sending at different URL but it’s using the Angular JS ($http) to make the SOAP request and read the
SOAP response
http://www.elylucas.net/post/tag/angularjs/
2. Below figure shown the how WAP (Web application proxy) allows the remote access to the
internet clients.
And how remote device authentication takes place to access the Backend system SharePoint/Excahnge
References:
http://blogs.technet.com/b/applicationproxyblog/archive/2014/10/01/introducing-the-next-version-of-
web-application-proxy.aspx
https://technet.microsoft.com/en-in/library/dn584113.aspx
https://technet.microsoft.com/en-in/library/dn528827.aspx

Batch Job Support
The SharePoint Online REST service supports combining multiple requests into a single call to the
service by using the OData $batch query option. For details and links to code samples, see Make
batch requests with the REST APIs. This option is not yet supported for on premise SharePoint.

Debugging
When you’re doing more complex operations—especially when you’re performing operations that
require the POST HTTP verb—you’ll need to use an HTTP tracing utility in order to debug your HTTP
requests. SharePoint returns error messages whenever you make a bad request, and those messages
can tell you a lot about what’s going wrong with your requests. For example, your application or user
may simply not be authorized to get certain kinds of information from SharePoint. At other times,
you may have constructed an invalid JSON object, or you might have assigned an invalid value to a
property.
Some frameworks provide HTTP tracing utilities for you. You can use trace.axd (bit.ly/8bnst4) when
you’re working with ASP.NET applications. If you’re sending requests directly from your browser, as
with JavaScript, you can use Fiddler (fiddler2.com/fiddler2). We used Fiddler to generate the sample
HTTP responses we included in this article.

SharePoint 2013 REST API & Remote Authentication

More Related Content

What's hot (8)

Viewers also liked (12)

Similar to SharePoint 2013 REST API & Remote Authentication (20)

SharePoint 2013 REST API & Remote Authentication