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://%3cserver%3e/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://%3cserver%3e/site/_api/site

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 endpoint HTTP method Result
web/title GET Get the list title
lists GET Get all lists from a site
lists/getbytitle(‘listname’) GET Get a specified list’s metadata
lists/getbytitle(‘listname’)/items GET Get items from a specified list
lists/getbytitle(‘listname’)?select=Title GET Get a specific property of an item
lists POST Creates a list
lists/getbytitle(‘listname’)/items POST Add 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.

Criteria Result
$select Sets the field names for returned result
$filter Sets the members of a collection
$top Sets the number of items to return
$skip Let you skip first n items from the result
$orderby Let 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.

Operator Description
Logical Operators
Eq Equal
Ne Not equal
Gt Greater than
Ge Greater than or equal
Lt Less than
Le Less than or equal
And Logical and
Or Logical or
Not Logical negation
String comparison
startsWith Starts with a specified text
endsWith Ends with a specified text
replace Replace a string
tolower Convert to lower case
toupper Convert to upper case
trim Removes 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.

comments
0