Understanding the Office 365 Discovery Service API Flow

Scot Hillier

by Scot Hillier on 10/7/2014

Share this:
Print

Article Details

Date Revised:
11/6/2014


UPDATE: Since this article was written, the Discovery Service has moved out of preview.

The Discovery Service now supports version endpoints.

Preview: https://api.office.com/discovery/me (OData v3)
Release: https://api.office.com/discovery/v1.0/me (OData v4)

 

As more people and organizations move into the cloud, developers will increasingly write applications that leverage the rich store of contacts, mail, events, and documents that are available through the Office 365 APIs. Because Office 365 contains many tenancies, however, it can be a challenge to locate the proper REST endpoint for the person using an application. The Discovery Service allows developers to find these endpoints dynamically, which simplifies the task of writing an application that works across tenancies.

While the Office 365 APIs do a good job of abstracting away the complexities of using the Discovery Service, it’s still important for developers to understand what’s going on under the covers. In this article, I’ll take a look at how the Discovery Service flow works so you can better understand its role in an Office 365 application.

The scenario I’ll use for the article involves reading the files from the current user’s OneDrive for Business library in Office 365. The OneDrive for Business library is available in SharePoint Online by clicking the OneDrive link in the header. This will take you to a special Document Library within your Personal Site.

1

Figure 1, Linking to OneDrive for Business

  2

Figure 2, The OneDrive for Business Library

 

FirstSignIn

In order to get started with the Discovery Service, you first need to know whether you are dealing with a Microsoft Account or an Organizational Account. The FirstSignIn API forces the user to a login page to enter their account and then returns the endpoints you’ll need to continue working with the Discovery Service. You can see how the FirstSignIn API works by starting Fiddler and clicking the following link.

https://api.office.com/discovery/me/FirstSignIn?redirect_uri=http://www.microsoft.com&scope=MyFiles.Read

You will be asked to provide your account name and then redirected to the Microsoft site. Normally, the redirection would be to your application, but this makes it easy to see what is happening. When you arrive at the Microsoft site, examine the session in Fiddler and you’ll see that endpoint information was returned for your account.

3

Figure 3, Return value from FirstSignin

 

Authorize

The next step in the discovery process is to get an Access Token using the authorization service endpoint returned by the FirstSignIn API. The authorization URL requires you to provide the Client Id of the application that will be accessing the OneDrive for Business files as well as a Redirect Uri to launch after authentication completes. The following URL shows a sample.

https://login.windows.net/common/oauth2/authorize?response_type=code&client_id=adbee37d-bc9a-4235-a63b-ae504b55589e&login_hint=scot%40msacademy1.onmicrosoft.com&redirect_uri=http%3A%2F%2Fdiscoveryflowapp

The authorization URL will force the user to sign in and then return an Authorization Code as a query string parameter. The following shows a sample of the resulting URL.

http://discoveryflowapp/?code=QA5...3438rxYWfhCw_xkNGUqGegIAA&session_state=98db4d01-c319-421b-be60-175b48e4f537

Once you have an Authorization Code, you can POST that Authorization Code to the token service endpoint. In the body of the POST, you must also provide some other key information (shown below), and you will get an Access Token and Refresh Token in return. The following is the URL provided by the FirstSignIn response:

https://login.windows.net/common/oauth2/token

4

Figure 4, Required POST Parameters

  5

Figure 5, Returned Access and Refresh Tokens

 

Discovery

Once you have an Access Token, you can finally call to the Discovery Service and get the endpoint for the current user. The Discovery Service is a simple GET request to the endpoint returned by the FirstSignIn call.

https://api.office.com/discovery/me/services

The return value is a JSON object with information about the service endpoints. For the OneDrive for Business library, the endpoint will refer to the user’s Personal Site and the MyFiles capability as shown below.

6

Figure 6, Returned Endpoint Information

Once you have the proper endpoint, you can then make subsequent REST calls to perform CRUD operations.

Summary

The Discovery Service allows you to find the service endpoints for contacts, events, e-mail, and documents for the current user. In order to use it you must follow a sequence of events designed to authorize the application and discover the endpoints. This flow can be summarized as:

  1. Call FirstSignIn endpoint

  2. Retrieve authorization, token, and discovery endpoints

  3. Call the authorization endpoint

  4. Retrieve an Authorization Code

  5. Call the token endpoint

  6. Retrieve an Access Token

  7. Call the discovery endpoint

  8. Retrieve service endpoints for mail, calendar, contacts, or documents

  9. Make subsequent REST calls to the service endpoints to perform CRUD operations

 

 

 

 


Topic: Development

Sign in with

Or register