There are many options out there for programming against the SharePoint object model. You can use all sever side code using the server side object model, everything client side using JavaScript and the CSOM (client side object model). You can even use Silverlight to access your SharePoint objects. One of the newest methods, and one that I’m excited about, is using the new SharePoint REST API. Making RESTful service calls is now available using SharePoint 2013, which makes creating pages and web parts very simple.

You can access most of your SharePoint objects via REST, but I am just going to look at lists for the moment. I will show you how to first read something from a list and then how to insert an item into that list.

The Model

For this example we are going to have a list already created named ‘Employees’ that has 5 fields.

  1. Title (I changed the display Name to Name)
  2. Address
  3. Department
  4. Salary
  5. Manager

Selecting From a List

The whole basis for RESTful queries is the URL and SharePoint makes this very easy for you. In this example let’s assume that our employees list is at the root of our site. In order to select all items from this list we would simply query the following URI:

https://mysite.com/_api/web/lists/getByTitle('employees')/items.   

The ‘_api’ tells SharePoint that this is going to be a REST query, and the rest of the string tells it where to find this list. A normal REST query would look like this:

https://mysite.com/_api/web/lists/employees/

But since this is SharePoint things are always a little bit different. Instead of referencing the list directly in the URI you must find the list by title. There is also an option to find by GUID, but using the title is a bit simpler to read in my opinion.

That query will give you every property of every item in your list. Sometimes this might by OK, but I would assume that most of the time this is going to be overkill. I queried my list with Fiddler and this is the first entry of the result set that came back.

full query set

You can see all of my custom properties in there, but the rest of the stuff I really don’t care about. Let’s trim this list a little bit by adding a query string to the end of my URI I can tell SharePoint to only give me back certain items.

 https://mysite.com/_api/web/lists/getByTitle('employees')/items?$select=Address,Department,Manager,Title,Salary

simplified query

This is the same record that I selected from above and obviously this is a lot lighter than my first query, so you would want to make sure you trim down the items you are returning to only the items you actually need. Also note that in the Model section above that I renamed the default Title field to Name, however that is just a display name. So when you are querying the list you must give the static name which is Title in this case. You can use most of the ODATA protocol in order to page through the list or do some filtering but I will leave that as an exercise for you.

Inserting a List Item

Inserting an item is just as easy as selecting an item and in fact we are going to be using the same URI and just change our HTTP verb from GET to POST.
We start with https://mysite.com/_api/web/lists/getByTitle(‘employees’)/items just like before, but this time we are going to need a payload to send along with this query so SharePoint knows to insert it. My payload data looks like the following.

 { '__metadata': { 'type': 'SP.Data.EmployeesListItem' }, 
    'Title':  'Tony Stark',
    'Department' : 'Research', 
    'Salary':  '2,000,000', 
    'Manager':  'Pepper Potts',
    'Address':  '23 Ironman Way, New York, NY'
 };

We are telling SharePoint what type of object we are inserting, in this case SP.Data.EmployeesListItem. Then we just pass along as a JSON string representation of everything that we want to fill out about the item. Just that simple.

We POST against this URL and SharePoint takes care of the rest.

Summary

  • SharePoint 2013 exposes a RESTful service to access lists and other elements
  • RESTful queries are quickly becoming the standard for web services instead of the older SOAP standard
  • Using RESTful queries in SP 2013 allows developers to access SharePoint elements without having to write any complex code

This post is also over on my company site