Getting Started with the Office 365 APIs

This weekend I had the pleasure of speaking on a couple of Office Development topics at Silicon Valley Code Camp, as well as the East Bay.NET user group meeting on Thursday (with special Halloween guest). It was great to pack three talks into one week as I’ve been doing so much internal-facing work lately, that I have been really itching to get back out to speak in front of the developer community.

One of the areas I’ve been working in for a while is building SharePoint Apps. Office and SharePoint Apps let you customize the Office and SharePoint experiences with your own customizations. Apps are web-based, and you use HTML and JavaScript to customize Office (Outlook, Word, Excel, PowerPoint) and SharePoint itself.

image

For more info on apps, see the MSDN Library: Apps for Office and SharePoint

We’ve also been working on another programming model that I’m really jazzed about. It allows you to build your own custom apps and consume data from Office 365 (Sites, Mail, Calendar, Files, Users). They are simple REST OData APIs for accessing SharePoint, Exchange and Azure Active Directory from a variety of platforms and devices. You can also use these APIs to enhance custom business apps that you may already be using in your organization.

image

To make it even easier, we’ve built client libraries for .NET, Cordova and Android. The .NET libraries are portable so you can use them in Winforms, WPF, ASP.NET, Windows Store, Windows Phone 8.1, Xamarin Android/iOS,. There’s also JavaScript libraries for Cordova and an Android (Java) SDK available.

image

If you have Visual Studio this gets even easier by installing the Office 365 API Tools for Visual Studio extension. The tool streamlines the app registration and permissions setup in Azure as well as adds the relevant client libraries to your solution via NuGet for you.

Before you begin, you need to set up your development environment.

image

Note that the tools and APIs are currently in preview but they are in great shape to get started exploring the possibilities. Read about the client libraries here and the Office 365 APIs in the MSDN Library. More documentation is on the way!

Let’s see how it works. Once you install the tool, right-click on your project in the Solution Explorer and select Add – Connected Service…

image

This will launch the Services Manager where you log into your Office 365 developer site and select the permissions you require for each of the services you want to use.

image

Once you click OK, the client libraries are added to your project as well as sample code files to get you started. The client libraries help you perform the auth handshake and provide strong types for you to work with the services easier.

The important bits..

const string MyFilesCapability = "MyFiles";
static DiscoveryContext _discoveryContext;

public static async Task<IEnumerable<IFileSystemItem>> GetMyFiles()
{
    var client = await EnsureClientCreated();

    // Obtain files in folder "Shared with Everyone"
    var filesResults = await client.Files["Shared with Everyone"].
        ToFolder().Children.ExecuteAsync();
            
    var files = filesResults.CurrentPage.OrderBy(e => e.Name);

    return files;
}
    
public static async Task<SharePointClient> EnsureClientCreated()
{
    if (_discoveryContext == null)
    {
        _discoveryContext = await DiscoveryContext.CreateAsync();
    }

    var dcr = await _discoveryContext.DiscoverCapabilityAsync(MyFilesCapability);
            
    var ServiceResourceId = dcr.ServiceResourceId;
    var ServiceEndpointUri = dcr.ServiceEndpointUri;

    // Create the MyFiles client proxy:
    return new SharePointClient(ServiceEndpointUri, async () =>
    {
        return (await _discoveryContext.AuthenticationContext.
            AcquireTokenSilentAsync(ServiceResourceId, 
            _discoveryContext.AppIdentity.ClientId,
            new Microsoft.IdentityModel.Clients.ActiveDirectory
                .UserIdentifier(dcr.UserId, 
                Microsoft.IdentityModel.Clients.ActiveDirectory
                .UserIdentifierType.UniqueId))).AccessToken;
    });
}

This code is using the Discovery Service to retrieve the rest endpoints (DiscoverCapabilityAsync). When we create the client proxy, the user is presented with a login to Office 365 and then they are asked to grant permission to our app. Once they authorize, we can access their Office 365 data.

If we look at the request, this call:

    var filesResults = await client.Files["Shared with Everyone"].
        ToFolder().Children.ExecuteAsync();

translates to (in my case):

GET /personal/beth_bethmassi_onmicrosoft_com/_api/Files('Shared%20with%20Everyone')/Children

The response will be a feed of all the file (and any sub-folder) information stored in the requested folder.

Play around and discover the capabilities. There’s a lot you can do. I encourage you to take a look at the samples available on GitHub:

Also check out these video interviews I did this summer to learn more:

Enjoy!