Discovery Service REST API reference
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:
- What cloud the user belongs to
- Where the app can send the user to log in
- 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 |