Discovery Service REST API reference

  • Article

Applies to: Office 365

Note

The Office 365 discovery service and SDK for .NET are being deprecated beginning January 10, 2018, and will be fully decommissioned on November 1, 2019. Start using Microsoft Graph to access Office 365 data in a single endpoint. For more details, see our announcement.

Use the Office 365 Discovery Service

To interact with the Discovery Service API you send HTTP and OData requests. Discovery Service supports discovering Calendar, Contacts, Mail, MyFiles (for OneDrive and OneDrive for Business service endpoints), Notes (for OneNote), and RootSite (for SharePoint).

The Resource ID for Discovery Service: ResourceId = https://api.office.com/discovery/.

For code samples on how to use the Discovery Service API to find endpoints for services that you access using the Office 365 APIs, see Office 365 APIs: How to use Discovery Service and Office 365 Discovery Service sample.

Note

The Discovery Service only provides functionality for the Office 365 online environment and does not work for on-premises deployments.

Versioning

The following are the Discovery Service versions.


Discovery Service API endpoint Description
https://api.office.com/discovery/v1.0/me Supports a single API endpoint per service for the released version of the Office 365 APIs.

Returns OData v4 (https://www.odata.org/documentation/odata-version-4-0/) by default.
https://api.office.com/discovery/v2.0/me Supports multiple API endpoints per service for the released version of the Office 365 APIs.

Returns OData v4 (https://www.odata.org/documentation/odata-version-4-0/) by default.

Discovery Service operations

Initial sign in

This brings the client to a web page where the user enters account information. It returns the endpoints needed to continue with Discovery Service. This is used the first time a user tries your application.

It tells your application:

  1. What cloud the user belongs to
  2. Where the app can send the user to log in
  3. Where to go to get a token

Parameter Type Description
scope string A space-delimited list of capability.operation tokens. This scope is in Office 365 terms.

Example: MyFiles.Write or Mail.Read
redirect_uri string URI to redirect to after authorization is completed.

Example: https://contoso.com/continue
lcid string Optional. A decimal LCID to localize the Email HRD UI.

Example: 1031

Note This API intentionally doesn't accept the user email because that might compromise the user privacy by sending the user email out of the current domain.

Response Description
302 Found The response body contains values about the app and the user

Response body item Description
Location: redirect_URI URI to redirect to after authorization is completed.
?user_email=... The email address the user entered.
&account_type=... 1 - Microsoft account (Live)
2 - Organizational account (Office 365)
&authorization_service=... Endpoint URL where the client can get an authorization code.
&token_service=... Endpoint URL where the client can exchange an authorization code for an access token and a refresh token.
&scope=... The original scope translated for the target realm. Clients only need to know Office 365 scope terms. If the target realm is Live, the original Office 365 scope is translated into Live terms.
&unsupported_scope=... If there are scope items that cannot be translated, they are compiled into unsupported_scope without a change.This is necessary because each authorization service understands scope only in its own terms. Because the Office 365 authorization service doesn't accept a scope parameter, both scope and unsupported_scope are returned empty.
&discovery_service=... Endpoint URL where the client can discover target services.
&discovery_resource=... Resource identification of Discovery Service. It must be passed in to the token service as part of the token request for Discovery Service.

Note

All this information is static for this user account. Therefore clients should cache it, and then reuse it to avoid annoying the user with unnecessary UI.

Example

var firstSignInUri = new Uri(string.Format("https://api.office.com/discovery/v1.0/me/FirstSignIn?redirect_uri={0}&scope={1}", TerminalUriText, Scope));
var terminalUri = new Uri(TerminalUriText);

//Starting authorization
var webAuthResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, firstSignInUri, terminalUri)
   .AsTask().ConfigureAwait(continueOnCapturedContext: true);

//Authorization finished
If (webAuthResult.ResponseStatus == WebAuthenticationStatus.Success)
{
var userEmail = MyExtractParamter("user_email",webAuthResult.ResponseData);
var accountType = MyExtractParamter("account_type",webAuthResult.ResponseData);
var authorizationService = MyExtractParamter("authorization_service",webAuthResult.ResponseData);
var tokenService = MyExtractParamter("token_service", webAuthResult.ResponseData);
var discoveryService = MyExtractParamter("discovery_service", webAuthResult.ResponseData);
var scope = MyExtractParamter("scope",webAuthResult.ResponseData);
var unsupportedScope = MyExtractParamter("unsupported_scope", webAuthResult.ResponseData);

MyCacheUserInfo(...);
}

Discover specific services

Use the /Services API to get the endpoint of a specific service.


Headers Description
Authorization An access token obtained during the Authorization phase.

Example: Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
Accept Optional. This header controls the format of the response payload:
For Atom: application/atom+xml

For JSON: application/json;odata=verbose

If this header is omitted, the default is Atom.

Example: Accept: application/json;odata=verbose

Parameters Type Description
$select string Optional. A comma-separated list of object properties. Causes the service to project only the selected properties. It is used to conserve bandwidth by not downloading properties that are not used by the app. See https://www.odata.org/docs/.

Example: Capability,ServiceUri
$filter string Optional. An OData predicate that filters the original result set. It is used to conserve bandwidth by not downloading object instances that are not used by the app. See https://www.odata.org under the Documentation tab for available predicate functions.

Response Meaning Description
200 OK The response body contains a list of ServiceInfo schema entries projected, filtered, and encoded according to the OData request. See the definition of the ServiceInfo schema schema.

Example

var url = string.Format("https://api.office.com/discovery/v1.0/me/services", discoveryService);

var request = HttpWebRequest.CreateHttp(url);
request.Method = "GET";
request.Headers["Authorization"] = "Bearer " + accessToken;

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

Learn what services are discoverable

Use the /AllServices API to learn all of the discoverable capabilities along with the services that implement them. /AllServices accepts anonymous requests and thus doesn't require an access token.


Headers Description
Accept Optional. This header controls the format of the response payload:
For Atom: application/atom+xml

For JSON: application/json;odata=verbose

If this header is omitted, the default is Atom.

Example: Accept: application/json;odata=verbose

Parameters Type Description
$select string Optional. A comma-separated list of object properties. Causes the service to project only the selected properties. It is used to conserve bandwidth by not downloading properties that are not used by the app. See https://www.odata.org/docs/.

Example: Capability,ServiceUri
$filter string Optional. An OData predicate that filters the original result set. It is used to conserve bandwidth by not downloading object instances that are not used by the app. See https://www.odata.org under the Documentation tab for available predicate functions.

Response Meaning Description
200 OK The response body contains a list of ServiceInfo schema entries projected, filtered, and encoded according to the OData request. See the definition of the ServiceInfo schema schema.

Example

var request = HttpWebRequest.CreateHttp("https://api.office.com/discovery/v1.0/me/services");
request.Method = "GET";
request.Headers["Accept"] = "application/json;odata=verbose";

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

ServiceInfo schema

The /services API and /allservices API APIs use ServiceInfo entries in their response body.


Property Type Example
capability String MyFiles
serviceId String
serviceName String O365_SHAREPOINT
serviceEndpointUri String https://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceId String https://contoso-my.sharepoint.com

See also