Table of contents
TOC
Collapse the table of content
Expand the table of content
Last Updated: 11/1/2017

Discovery Service REST API reference

Applies to: Office 365

Use the Office 365 Discovery Service

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. See more details in our announcement.

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 Office 365 online environment and does not work for on-premises deployments.

Versioning

The following are the Discovery Service versions.

Discovery Service API endpointDescription
https://api.office.com/discovery/v1.0/meSupports a single API endpoint per service for the released version of the Office 365 APIs.
Returns OData v4 (http://www.odata.org/documentation/odata-version-4-0/) by default.
https://api.office.com/discovery/v2.0/meSupports multiple API endpoints per service for the released version of the Office 365 APIs.
Returns OData v4 (http://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

ParameterTypeDescription
scopestringA space-delimited list of capability.operation tokens. This scope is in Office 365 terms.
Example: MyFiles.Write or Mail.Read
redirect_uristringURI to redirect to after authorization is completed.
Example: https://contoso.com/continue
lcidstringOptional. 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.
ResponseDescription
302 FoundThe response body contains values about the app and the user
Response body itemDescription
Location: redirect_URIURI 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.


HeadersDescription
AuthorizationAn access token obtained during the Authorization phase.
Example: Authorization: BEARER 2YotnFZFEjr1zCsicMWpAA...
AcceptOptional. 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
ParametersTypeDescription
$selectstringOptional. 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 http://www.odata.org/docs/.
Example: Capability,ServiceUri
$filterstringOptional. 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 http://www.odata.org under the Documentation tab for available predicate functions.
ResponseMeaningDescription
200OKThe 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.


HeadersDescription
AcceptOptional. 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
ParametersTypeDescription
$selectstringOptional. 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 http://www.odata.org/docs/. Example: Capability,ServiceUri
$filterstringOptional. 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 http://www.odata.org under the Documentation tab for available predicate functions.
ResponseMeaningDescription
200OKThe 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.


PropertyTypeExample
capabilityStringMyFiles
serviceIdString
serviceNameStringO365_SHAREPOINT
serviceEndpointUriStringhttps://contoso-my.sharepoint.com/personal/alexd_contoso_com
serviceResourceIdStringhttps://contoso-my.sharepoint.com

Additional resources

© 2018 Microsoft