SharePoint 2013 REST API

REST stands for 'Representational State Transfer' and it is an architectural pattern for creating an API that uses HTTP as its underlying communication method.

History of REST API in SharePoint

• SharePoint 2010
• Introduced REST API
• /_vti_bin/ListData.svc
• Exposed CRUD operations on list data
• SharePoint 2013
• ListData.svc was deprecated (still available for backward compatibility)
• RESTful operations added to the /_vti_bin/Client.svc
• An alias for /_vti_bin/Client.svc was added as /_api

SharePoint REST service architecture

• The Client.svc web service in SharePoint handles the HTTP request, and serves the appropriate response in either Atom or JSON (JavaScript Object Notation) format. 
• Your client application must then parse that response. 
• Because of the functionality and ease of use that client object models provide, they remain the primary development option for communicating with SharePoint sites by using .NET Framework managed code, Silverlight, or JavaScript.

Use HTTP commands with the SharePoint 2013 REST service

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

Construct REST URLs to access SharePoint resources

• 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

Read Operations (Get)
To read information from a REST endpoint, you must know both the URL of the endpoint and the OData representation of the SharePoint entity that is exposed at that endpoint.
For Example: You can view the results returned by the following urls in your browser.

• "http://<your site>/_api/web/lists(guid'<list id>')" gets the list with the specified GUID.
• "http://<your site>/_api/web/lists/getByTitle('Task')/items" gets the items in the Task list.

Note: You can navigate to the above URL in your browser and see the XML that gets returned. When you make the request in code, you can specify whether to receive the OData representation of the lists in XML or JSON.

Filter and Sort Operations
The SharePoint REST API provides a variety of attributes for additional operation like sorting or filtering data while retrieving items.
For Example:

• "http://<your site>/_api/web/lists/getByTitle('Task')/items?$select=Title" retrieves only the Title column in the list. 
• "http://<your site>/_api/web/lists/getByTitle('Task')/items?$orderby=Title asc" sorts the items in ascending order of the Title.

Following are some of the commonly used attributes

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

Operators
SharePoint REST service supports OData query operators for comparison and other operations while filtering data.
For Example:

• "http://<your site>/_api/web/lists/getByTitle('Task')/items?$filter=Title eq 'Testing'" retrieves only the items with the Title column as Testing.

Following are some of the commonly used operator

Numeric Operators	Operation
Lt	less than
Le	less than or equal
Gt	greater than
Ge	greater than or equal
Eq	equal to
Ne	not equal to
String Operators	Operation
startsWith	starts with string
substringof	substring of a string
Eq	equal to
Ne	not equal to

Using SharePoint REST API with JavaScript\JQuery
The SharePoint REST API can be used with JS or JQuery to perform the basic CRUD operations within SharePoint.
For Example: The following JavaScript function uses the JQuery ajax method to retrieve the items of the "Tasks" list using the REST API url.

function getItems()

{

$.ajax({

url:  "http://<your site>/_api/web/lists/getByTitle('Task')/items",

type: "GET",

headers: { "accept": "application/json;odata=verbose", },

success: function (data) {

console.log(data.d.results);

},

error: function (error) {

alert(JSON.stringify(error));

}

});

}

REST API Coverage

The SharePoint REST API supports operation on all the following aspects:

• Site Collections, Subsites, Features, Event Recievers, 
• Lists, Items, Fields, Content Type, Views, Forms, Folders
• Libraries, Files,
• Users, Roles, Groups, User Profiles, Feeds
• Search

I hope this post was helpful. We will see many more applications of REST API in the upcoming posts.