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