Programming Office 365: Hands On with Microsoft's new APIs

Analysis Microsoft has announced new APIs and mobile software development kits for Office 365, its cloud platform for email, document storage, and collaboration.

Office 365 uses Azure Active Directory (AD) for authentication, and the company is pushing the idea of using this not only for Office 365, but also as a corporate cloud identity for other apps and services.

This gives the user single sign-on for business applications as well as email, and giving the organization a single point of management for managing users. If a user leaves, the account can be disabled once, immediately removing access to cloud applications.

Coming in Windows 10 is the ability to sign into Windows using Azure AD, as an alternative to traditional domain-joined PCs. It is likely to be a popular option, especially for small businesses.

The implication for developers is that they will get requests to write applications that use Azure AD for authentication. There is also an option to hook into Office 365 services such as email or OneDrive for business storage.

At TechEd in Barcelona, Microsoft made three announcements. One was that REST APIs for Office 365 are now out of preview. These APIs cover Mail, files (SharePoint/OneDrive for business), Calendar and Contact.

The second announcement was of mobile SDKs for Android and iOS.

Third, if you write a SharePoint online web application, you can now add it to an app launcher — a sort of online Start menu in Office 365.

The background to the Office 365 APIs is that Microsoft is using OData, a Microsoft-sponsored open standard, for its REST APIs. OData has its own XML schema definition language, called Common Schema Definition Language (CSDL), which describes the API, in the same way that WSDL (Web Services Description Language) does for the older and now unpopular SOAP web service standard. You can generate code libraries to access an OData API by parsing the CSDL descriptions, and this is how the Office 365 SDKs are generated, as explained here.

Authorisation is handled using OAuth, an open standard also used by Google and others.

So how does this stuff work? I have tangled with this before, in the context of developing a web application that uses Azure AD. Microsoft has made this easy, you might think, with a wizard in Visual Studio that sets up an ASP.NET application to use Azure AD.

This does work, but I discovered that Microsoft’s wizard-generated app makes no provision for querying Azure AD groups. It only gives access to basic information about the logged-in user. If you want to query Azure AD groups (and typically for business applications you will), then you need an additional API called the Azure Graph API, for which you can choose between old .NET libraries that are deprecated, or new ones that are in preview, neither option being attractive to enterprise developers.

Or you can roll your own code for using the REST API, which is a bit fiddly. I got my application working, but only after a long journey through various code samples and experiments.

I was reminded of this when trying the new Office 365 APIs. I went to the Getting Started page, which directs you to install the Office 365 tools for Visual Studio 2013. This enables an option to add a “connected service” to an app under development. Once you have done that, you have to follow several steps, including setting up an Azure subscription with Azure AD linked to the Office 365 account you want to target, registering an application in Azure AD, obtaining a ClientID and Redirect URI which you will embed in your code, and then adding the code to your app to call the Office 365 services.

The procedure for iOS and Android is similar, except that you download the mobile SDK for the target platform and use Xcode, Eclipse, or your favourite IDE or editor instead of Visual Studio. Another option is to stick with .NET and use Xamarin’s cross-platform compiler to target iOS and/or Android.

Next, I hit the Documentation link on the Getting Started page. This takes you to a REST API reference, together with a link to an article on how to Integrate Office 365 APIs into .NET Visual Studio projects. This describes a three-stage process:

1. Call a Discovery Service to obtain the correct endpoints for your REST API calls, which may be specific to a particular installation.

2. Get an access token to authorize Office 365.

3. Finally, write code that actually uses the service you are targeting, either Outlook or SharePoint.

The only way to learn how this works is to try it, so I followed one of Microsoft’s web trails to find some samples. The OAuth standard does require an intricate token exchange dance. Consider, for example, the 6 steps to use the Discovery Service. It goes something like: request an access token; the user authenticates; Azure AD issues an authorization code; you use the authorization code to request an access token and an additional refresh token; you call the discovery service with the access token; then you use the refresh token to get an access token for the required Office 365 resource. Phew.

This complexity does not get in the way if suitable libraries wrap it successfully, but often this is not the case.