Skip to main content

Introduction to REST API with OData Operators in SharePoint 2013

What is REST API?

REpresentational State Transfer Application Program Interface (REST API)  is an architectural style which consists of a set of constraints applied to components, connectors and data elements within a system. REST-based systems typically communicate over HTTP, using  verbs such as GET, POST, PUT and DELETE.

SharePoint 2013 supports REST service which helps in executions similar to Client Object Model scripts. Using REST API we can interact remotely with SharePoint by using any technology of our choice that supports REST web service requests. This empowers developers to perform Create, Read, Update and Delete (CRUD) operations from their solutions, client applications or SharePoint apps using REST and Open Data Protocol (OData).

How REST API works in SharePoint 2013

SharePoint 2013 uses two different approaches to authorize user access to the site with REST. Firstly, when you use a remotely hosted application, an OAuth token with Microsoft Access Control Service is used as secure token server. Another alternative approach is used while accessing from client side scripting where the logged-in user’s permission is sufficient for authentication. SharePoint REST helps authenticated users to directly interact with SharePoint objects.

SharePoint resources are accessed using a RESTful HTTP request using Open Data Protocol (OData) which resulta from client-object model API. Consider the below example:

http://<server>/site/_api/lists/getbytitle(‘listname’)

The client.svc web service in SharePoint handles this HTTP request and returns the response in JSON format. A client application handling this request can parse the response.

REST !

How to Construct RESTful URLs to access SharePoint resources

REST service always uses the main entry point to SharePoint as the site collection and the site of the specified context. The site collection is accessed using the below url:

http://<server>/site/_api/site

And, to access a sub-site you can generate url as:

http://<server>/site/_api/web

where <server> represents SharePoint server name and site represents path of the site

One can access the SharePoint data with below REST endpoints; prefix the endpoint with url http://<server>/site/_api/ to construct a fully qualified REST url.

URL endpointHTTP methodResult
web/titleGETGet the list title
listsGETGet all lists from a site
lists/getbytitle(‘listname’)GETGet a specified list’s metadata
lists/getbytitle(‘listname’)/itemsGETGet items from a specified list
lists/getbytitle(‘listname’)?select=TitleGETGet a specific property of an item
listsPOSTCreates a list
lists/getbytitle(‘listname’)/itemsPOSTAdd an item to a specific list

Open Data (OData) Standard Protocol

OData is a Standard protocol or a set of rules for creating RESTful calls. You can use OData system query options to control the result.

CriteriaResult
$selectSets the field names for returned result
$filterSets the members of a collection
$topSets the number of items to return
$skipLet you skip first n items from the result
$orderbyLet you sort result by a specific field

Some examples on how to use OData operators in RESTful calls:

http://<server>/site/_api/web/lists/getbytitle(‘Employee’)/items$top=10

This REST endpoint URL will return top 10 employees from the list ‘Employee’

http://<server>/site/_api/web/lists/getbytitle(‘Employee’)/items$select=FirstName,LastName,Email&$top=5

This url will have a response of top 5 employees from the list and the result will consists of only three fields from the list namely; FirstName, LastName and Email.

OData Operators

The query section of OData URI can be used to filter data in SharePoint REST service.

OperatorDescription
Logical Operators
EqEqual
NeNot equal
GtGreater than
GeGreater than or equal
LtLess than
LeLess than or equal
AndLogical and
OrLogical or
NotLogical negation
String comparison
startsWithStarts with a specified text
endsWithEnds with a specified text
replaceReplace a string
tolowerConvert to lower case
toupperConvert to upper case
trimRemoves white spaces

Few examples of getting SharePoint data using OData operators

http://<server>/site/_api/web/lists/getbytitle(‘Employee’)/items$select=FirstName,LastName,Email&$orderby=EmpID asc

http://<server>/site/_api/web/lists/getbytitle(‘Employee’)/items$orderby=EmpID asc&$filter=FirstName eq ‘John’

 Conclusion

SharePoint 2013 with REST interface is extensive and powerful enough to execute most of the operations for web and app developers. We have looked at the key ways to integrate SharePoint to other applications using REST API interface, but there are several other possibilities. The SharePoint 2013 SDK consists of a huge collection of resources for REST based development, which can be a reference.

Sreejith K B

Sreejith K B

Sreejith. B. works as Technical Lead with Trigent Software. Sreejith is a senior IT professional with over 12 years experience in Microsoft Technologies and web development tools using SharePoint and advanced frameworks such as AngularJS, Bootstrap, jQuery in product design and development. Sreejith comes with extensive experience in all stages of s software development life cycle including design, development and implementation.