Omicron Llama

Coding all day, every day.

SharePoint 2013 REST API in iOS

NOTICE: This post refers to my initial version of an attempt at this API. This version is now deprecated, please use the version detailed here instead.

This post and the included code is the result of a couple of weeks of confusion, hard work and a tonne of research and collaboration between myself and Becky Isserman. There is very little documentation out there on how to do this so we hope that some people will get some use out of this.

TL:DR – show me da code: https://github.com/jimmywim/SPRestAPI

I’ve written a proper usage guide to the API too, available here: https://github.com/jimmywim/SPRestAPI/wiki/Usage

All of this relates to the Office 365 offering of SharePoint Online, not the on-premises SharePoint Server 2013 (yet). The methods used here aren’t (I think) documented and things are subject to change, so I’ll try to keep the code up to date for those downloading this at a later date.

The basic task of using any sort of API with SharePoint is authentication. Getting SharePoint to know who you are and for you (the client software) to remember who you are is made easy with the Microsoft provided APIs (Managed and JavaScript Client Object Models), but there is very little out there for anything else. With the release of SharePoint 2013 and the App Model, there has been talk (that I’ve heard) that makes development for SharePoint using iOS, PHP, Ruby, in fact anything, possible. For iOS in particular, we haven’t seen much yet. So we decided to figure it out.

In the .NET world, Wictor Wilen wrote this post on actively authenticating to Office 365. His code demonstrates the steps performed using a helper class he wrote that handles the authentication and the cookie storage needed to remain authenticated. At the heart of his code is some Windows Identity Foundation classes that talks to the SharePoint Secure Store. To replicate what his code does for iOS, I had to use Fiddler Web Debugger to identity what the app was talking to and what messages it was sending.

As he explains in his blog (and as I’ve seen with Fiddler), there are 3 basic steps to authentication:

 

  1. Pass the username, password and intended site collection to the Secure Token Service exposed by Office 365
  2. Receive a secure token response from the STS, and pass it to your site’s login page.
  3. The response from your login page will redirect to your site’s home page, and also include 2 cookies needed to keep you logged in.

The first step is performed using WIF code, and essentially authors a SOAP envelope with your authentication data included. The response from this is packaged into a regular Web Request and sent to your site’s login page using standard .NET APIs. The cookies from this are then stored and added to each subsequent request to your SharePoint site to ensure you’re kept logged in. If you wish to ‘log out’, you only need to discard the cookies (and possibly make a request to SignOut.aspx, incase there is any Session information stored on the server that needs to be cleared).

So, let’s describe how I’ve implemented the above concepts into a re-usable framework for iOS. Hopefully I’ve made this as simple as possible, though at this stage the code can only issue GET requests, and therefore can’t add new data to a site.

I should probably point out that I’m no expert programmer in Objective C, having come from a C# background of nearly 8 years experience. There are parts of the code I don’t fully understand (in particular, the delegates) and parts that are just syntactically wrong or could be done better. I’m very open to suggestions on how to improve parts, even if just for widening my own understanding of the language.

First we need to authenticate. I do this using a class called SPClaimsHelper.

 

The call to GetTokens initiates the authentication process to log into SharePoint and retrieve your cookies. This class issues a delegate when this is completed to let your application proceed as ‘logged in’.

 

This code above simple logs that the tokens have been received and loads the next ViewController.

Once we’re logged in, we can then issue queries:

 

At this stage of development, you’ll see I’ve not implemented ‘remembering’ the site collection URL, so the request currently has to include this. Hopefully someone can do a more efficient implementation when using this code such that the site collection URL remains defined once and re-used for the queries.

An interesting point to note here is the ‘id’ parameter of the SPRESTQuery’s init method. Here I pass in a string with which I can identify which request has completed within the response’s delegate method.

Here’s an example of the delegate method handling this request (plus my shoddy idea of how delegates are structured, but hey – it works):

 

When we issue more requests from within the same ViewController (or other class) that has the SPRESTQuery’s delegate, we can use the requestId to identify which request has completed.

As you can see, the response XML is returned as an SMXMLDocument object, which comes thanks to these guys, for making an awesomely simple XML parser: https://github.com/nfarina/xmldocument

And that’s all there is to it!

Finally, here’s the link to the GitHub repository where I’ll be maintaining the code.

https://github.com/jimmywim/SPRestAPI

Cheers!

3 thoughts on “SharePoint 2013 REST API in iOS

Leave a Reply

Your email address will not be published. Required fields are marked *