Pro Office 365 Development, Second Edition (2014)
Chapter 8. Consuming Data with Office 365 APIs
Office 365 has provided a great set of products and services for the consumer from the beginning. By offering Office in the Cloud, business users have access to the best productivity tools available without the hassle of the infrastructure required to provide those tools.
However, the developer’s experience might not have been as great. The data only exists in the Cloud, so any applications or websites that need to use that data also have to access it from the Cloud. It has been doable, but not easy.
This chapter introduces the Office 365 APIs. The following chapters will dive deeper to explain the details of how these services work, and any requirements developers need to know about. These chapters will include applications built in Visual Studio to demonstrate the ease of development and the power of the services.
Introducing Office 365 APIs
Microsoft improves the ability for the developer to build applications and websites using Office 365 data by providing REST APIs and a standard means of authentication. Web applications, native applications in Windows 8, iOS, and Android apps, along with virtually any device can consume Office 365 data over the wire.
Note Microsoft declares the current release a Preview. As such, it is subject to change and evolution over time. The current release is only the beginning. The support is limited, yet powerful. In the future, limitations will be removed. Microsoft is dedicated to providing the ability to consume Office 365 data in web-enabled applications.
Before this release, developers had to rely on very different client libraries. Consuming data from SharePoint was a much different experience than consuming data from Exchange. Using client libraries inherently reduces the type of applications that could be developed.
Rather than separate libraries, Microsoft now provides unified REST APIs for the various types of data hosted in the cloud. This includes files, mail, and calendar data. To aid in accessing the cloud data, Microsoft has introduced a new Discovery Service. The current release offers a new File OData API for SharePoint 2013, an Exchange OData API, and expanded CSOM APIs along with the new Discovery Service.
More Unified Data Consumption
Now that data can be consumed using REST APIs, there is a more uniform process to development. The process to connect and consume data from the various sources has become a very similar process across the different options. Using web-based services tends to be similar regardless of the source. This places the process of using Office 365 data into more familiar territory for most developers.
Expanded Application Development
The new services also expand the options on what type of applications can consume Office 365 data. Nearly all types of applications have a means to call REST services. From native Windows 8 apps, to website, to iOS and Android apps, Office 365 is available over the wire. Authentication and authorization is handled using OAuth. Everything is done over the web, so any web-enabled application running on a web-enabled device can access Office 365 data. Figure 8-1 demonstrates how a user could access Office 365 data from any device through the web using the Office 365 APIs. Developers can now make this a reality with much greater ease. This is a very powerful addition.
Figure 8-1. Accessing Office 365 data over the wire through various devices
A New Foundation
Office 365 is built on the foundation of Microsoft Azure Active Directory (AD). Developers may be familiar with Active Directory, the service running in Windows Server that manages identity within the network and other on-premise resources. In terms of identity and access management, Azure AD provides a similar role, only for the cloud. This service allows organizations to manage their cloud-based identities against their cloud-based applications.
Microsoft Azure AD can function on its own. Organizations that do not run full networks on-premise, or who desire to manage their cloud-based resources separately from their local ones, can use Azure AD as a separate service. For those organizations expanding their on-premise resources to the cloud, Azure AD can integrate with the existing Active Directory. However Azure AD is configured to work, it provides all users a single sign-on experience for applications that are integrated.
Figure 8-2. Microsoft Azure AD authentication
Note Microsoft Azure AD offers much more than is covered here. For more information on Microsoft Azure AD, visit http://azure.microsoft.com/en-us/documentation/services/active-directory/.
New Discovery Service
Consuming data through web services can greatly enhance application development and user experience. For the developer, accessing the hosted service is typically easy, as long as you can find where the service is hosted. Thinking about how Microsoft might host Office 365 data along with the services to access that data, might cause some concern for how particular applications will be able to find the necessary service endpoints to access the Office 365 data.
Microsoft introduced their new Discovery Service to allow organizations to determine the proper URL for the services that access their data. This service begins with a single URL for Office 365 services, and requires only the user’s e-mail address to determine the proper endpoints. This allows the developer to begin at a common starting point and allows the application to determine the proper path for authorization and service endpoints to access the data desired for presentation and productivity. The Discovery Service will be discussed in detail in the next chapter.
Adding Office 365 APIs to a Visual Studio Project
Now that the overall fundamentals of the new Office 365 APIs have been presented, let’s get started on actually accessing them in an application. Microsoft provides the Office 365 API Tools for Visual Studio 2013 to simplify the process of accessing the available services.
Client Libraries
The Office 365 API Tools for Visual Studio 2013 provide a set of client libraries to streamline the process of accessing the Office 365 services. The services are REST services, so the client libraries are not required. They are provided to enhance the development experience within Visual Studio. These libraries will speed up the process of developing against these services for applications built within Visual Studio 2013. These client libraries are portable .Net libraries, allowing developers to use them in their Windows and web applications along with iOS and Android applications through Xamarin. Javascript versions of the libraries are also included for the applications that target an HTML/JavaScript application.
Note Earlier in the chapter, client libraries were presented as a negative to the development experience. In that case, the issue is that they are unrelated libraries and provided as the only means for accessing the hosted data. The Office 365 Tools for Visual Studio 2013 include libraries for a different purpose. These libraries are designed to speed up the development process. It is somewhat expected that most developers would build similar libraries around the REST services anyway, so Microsoft has provided these to solve the common problem. It is possible to bypass the client libraries and access the services directly. In development tools other than Visual Studio 2013, that is what would need to happen.
Installing the Office 365 API Tools for Visual Studio 2013
To setup Visual Studio 2013 to access Office 365 API, the Office 365 API Tools must be installed. This is an extension for Visual Studio, installed in a VSIX package. As of the writing of this book these tools are in Preview.
These tools extend Visual Studio 2013 to aid in development against the Office 365 APIs. They will work on any machine running Visual Studio 2013. They do not require SharePoint to be installed.
Take care where this is installed. As with any Visual Studio extension, these tools may be removed through the Extensions and Update dialog. This is found by clicking Tools, then Extensions and Update. Find the Officer 365 API Tools – Preview entry and click Uninstall.
Find the install package at http://aka.ms/Office365ApiToolsPreview.
1. Download the Office 365 API Tools - Preview. The download page should look similar to Figure 8-3.
Figure 8-3. Download Office 365 API Tools - Preview
2. Download the .vsix file. The VSIX Installer dialog box, similar to Figure 8-4, will appear.
Figure 8-4. VSIX Installer for Office 365 API Tools - Preview
3. Click the Install button
Figure 8-5. VSIX Installation Complete
Note An Office 365 account is required to use the Office 365 APIs. If you do not have an account, visit http://office.microsoft.com/en-us/tocreate one.
Now the Office 365 Tools for Visual Studio 2013 are installed on your machine and ready for development.
Adding Office 365 APIs to a Project
To enable any project to work with Office 365 APIs, they have to be configured using the Services Manager in Visual Studio. This includes signing into your Office 365 account. Once this is done, the proper assets will be added to your project along with sample code to demonstrate how to get started.
Choosing the Right Project Type
The Office 365 Tools for Visual Studio 2013 include client libraries. These are offered in .NET and JavaScript languages. Due to this, Office 365 APIs will only work with certain project types.
· ASP.NET MVC Web Applications
· ASP.NET Web Forms Applications
· .NET Windows Store Apps
· Windows Forms Applications
· WPF Applications
· Xamarin Android and iOS Applications
· Multi-device Hybrid Apps
While no one really likes to hear about limitations, this is not a small list. Developers can choose from a wide range of applications to build using these project types to offer functionality for their users.
Add Office APIs to the Project
For the example in this chapter, we will use an ASP.NET MVC Web Application. You can use any of the accepted projects types from the list above.
1. Create a new ASP.NET MVC Web Application in Visual Studio 2013
Figure 8-6. New ASP.NET MVC Web Application
2. Choose MVC options for the web application in the ASP.NET New Project dialog, as seen in Figure 8-7.
Figure 8-7. MVC options for new project
3. In the menu, click Project, then Add Connected Service. Figure 8-8 shows where this feature is found.
Figure 8-8. Adding Connected Service to existing project
4. Click the Sign In link in the Services Manager, under the Office 365 option. The screen should appear similar to Figure 8-9.
Figure 8-9. Services Manager in Visual Studio 2013
5. Sign into your Office 365 account. A dialog will appear similar to Figure 8-10.
Figure 8-10. Sign into Office 365
6. Once connected to the Office 365 account, a list of available APIs will display, as shown in Figure 8-11.
Figure 8-11. Available Office 365 APIs
7. Choose the API service for your project and click OK.
8. You may need to configure permissions for the service. If so, a dialog box, similar to Figure 8-12, will prompt you to make the appropriate choices.
Figure 8-12. Service Permissions requested from Office 365
The proper libraries are added to the project, references are configured, and sample code is made available to help start development against the selected Office 365 API. The list of actions completed by the tools depends upon the type of project and service that were selected.
Note The Services Manager allows for permissions management throughout the development process. Simply revisit this area within Visual Studio to change or add permissions at any time.
Summary
The Office 365 APIs are a powerful addition to the services provided by Microsoft’s productivity lineup. Office 365 opens a business or organization to the cloud and provides enhanced productivity without the infrastructure investment. The Office 365 APIs leverage the availability of that Office data and empowers developers to expand the productivity experience into custom websites and apps onto virtually any device.
The following chapters will demonstrate the ease and power of these APIs. You will see applications built in Visual Studio 2013 that consume data through the Office 365 APIs.