Inside Office 365’s APIs

Last year Microsoft CEO Satya Nadella said that the Office 365’s APIs were the company’s most strategic — and most valuable.

Designed to open Microsoft’s cloud productivity platform to developers, Office 365 APIs are collections of tools that simplify building Office’s cloud services into your apps. Microsoft’s cloud services are at the heart of its current strategy, and its APIs are a big part of how it delivers those services to everything from Android phones to Node.js Web applications. 

Using familiar REST APIs, and providing SDKs for common platforms, Microsoft is aiming to use Office 365 and Azure Active Directory as hubs where apps store files and users build collaborative relationships with others.

The underlying technologies Microsoft is using will be familiar to anyone building a modern app that connects to Web services. REST and OData are used to transfer data, while OAuth 2.0 is used for authentication. Drilling down into the APIs, you can start to see how Microsoft is exposing Office 365 to apps. Take email, for example. The structure of a call is based around a root URL that’s made up of a server name, the API version being used, and the user context.

Once you’ve constructed the appropriate root URL, you can start to make calls against the API. If you want to get the inbox messages for the logged-in user, just append “messages” to the root URL. For other folders, you’ll need the folder ID. The response can be large, as it contains details for all the messages in the folder, including content and a full set of headers. Perhaps the most useful element of this response is the message ID, which can be used in further calls to the API – including to obtain the full message, and even to download attachments.

Sending messages is a lot easier. You’ll need to create JSON content for the API call, which uses an HTTP post to the root URL’s sendmail method. You can create and send messages instantly or add a draft to a folder, which can then be updated and sent. Other options let you create and manage replies, forward messages, and delete messages from folders. Working with Office 365’s mail service is a lot like working with a database — complete with the familiar CRUD (Create, Read, Update, and Delete) operations.

Microsoft’s Office Dev Center has documentation for the full set of REST APIs. An online reference shows how to work with the key Office 365 services: with Mail, with Contacts, with Calendar, and with Files. There’s also the option to test code in an online sandbox before you add it to your applications, with a Web-based editor and code evaluation service. A sandbox like this is a useful tool, and Microsoft’s gives you the option of pasting in code in most popular languages, including JavaScript, PHP, and Ruby (and of course C# and Java).

Building single sign-on (via Azure Active Directory) into the APIs is also sensible. Users don’t want to sign in to get their mail — and again to get their files — especially if they’re using a single app. Azure Active Directory support means that registered apps get access to all the services they need, with all the permissions they need. You’ll need to register your apps with the service, listing the features apps need to access, making sure your users can’t use an app to access data they don’t need.

Microsoft’s choice of a technology-independent way of delivering its APIs makes a lot of sense. You can use the REST APIs with any language or service, or if you’re using iOS, Android, or Windows, you can use the Office 365 SDKs with your choice of development environment. Apple developers don’t need to switch from Xcode, Android’s get to use either Eclipse or the new Android Studio, and Windows developers can carry on using Visual Studio. There are plenty of language choice with the SDKs, with the iOS version supporting Swift and Objective C and the Visual Studio tools letting you work with next-generation Universal apps as well as with cross-platform Cordova and Xamarin projects.

The various Office 365 SDKs mean you don’t have to write your own REST code; especially as the SDKs handle managing authentication tokens for you. However, in many cases you’re going to have to do the work yourself, especially if you’re looking at working with technologies like Node.js or Ruby on Rails for Web-based projects. Building Mail REST URLs is complex, as is handling the appropriate OAuth tokens, but it’s essential if a Microsoft or third-party SDK doesn’t exist for the platform you’re using.

If you’re building an iOS app you can reduce risk and speed development up by using Microsoft’s iOS SDK, available on Github. There are code samples to help you get up to speed, and as the SDK is open source, there’s the option of modifying the code and making your own contributions.

Once you’ve set up the SDK in Xcode and added the appropriate headers to your app, along with code to authenticate with Office 365, you’ll find it’s a lot easier to write getMessages than constructing a REST URL and parsing the returned JSON code – and of course not having the headaches that come with using Web services by also taking advantage of iOS’s tools for working with asynchronous operations. Working with Android is very like working with the iOS SDKs. Methods have similar names to iOS, though there are more features in the Android SDK. For example, there’s the option of paging through large mailboxes, reducing the load on servers and on devices.

Microsoft’s Office 365 APIs are perhaps best thought of as the border between the app world and Microsoft’s productivity tools. They let you build apps into existing document and email-based workflows, allowing new users and devices to become part of the way your business works. Open APIs like these also let Microsoft expand its cloud platform beyond Windows – while still making money. All you need to take part is an Office 365 subscription.