Understanding the Office 365 API’s Discovery Service

The Office 365 APIs contain multiple endpoints such as contacts, calendar, mail, files and there’s even a way to talk to the SharePoint REST API. Microsoft has committed to working on future APIs for this suite and even thrown around some ideas like Yammer, Skype and a few others. There are a few challenges when working with these APIs as there are a few things you must know prior to calling them from within your code.

First, you must know the endpoint’s unique ID which is called the Resource ID. This is the unique ID of the resource endpoint that you use when asking the Azure token endpoint for an access token in the authentication process.

Second, you must know the endpoint of the resource… called the Resource URL. Some services have the same endpoint URL, for instance the contacts, calendar and mail endpoints all share the same Exchange Online endpoint of https://outlook.office365.com. However others may be different, like the files endpoint includes some stuff in the URL about the specific user. You should never hardcode the resource URL into your code… you should always ask for it because who knows it it changes one day in the future.

And lastly, the other thing you need to know is what permissions you have granted to the application. While your application may be coded to read a user’s contacts, wouldn’t it be nice to check if that permission has been granted (or revoked) by the user instead of trying to issue the request and checking if you get a HTTP response of 401, access denied, error?

All three of these things can be obtained by simply using the Discovery Service. This service enables the developer to query for all services available or just for the services that the current user has been granted access to. It is one of the services that you can hard code the resource ID and URL in for your application. The discovery service’s resource ID is https://api.office.com/discovery/ and the endpoint is https://api.office.com/discovery/v1.0/me. it is an authenticated service so you will need to obtain an access token from the Azure token endpoint as I’ve explain in previous posts.

And don’t forget to include the trailing “/“ on the resource ID. That trips me up all the time. If you try to call it without the trailing slash, you’ll get an error that it doesn’t exist. And also make sure you include the trailing slash when you request an access token because when you get the access token, if it doesn’t include the trailing slash, then the intended audience field in the access token will not match the real discovery service resource ID so when you call the resource, it will not pass validation of the token. Oh man, I can’t tell you how many times I’ve screwed this up and beaten my head on my desk trying to figure it out.

There are two things you can call in the discovery service: (1) a list of all services and (2) a list of those services you have access to. To call the first one, include /allServices on the endpoint. To get all services you call /services. They will give you a lot of information about services, but these are the two that you’ll need to call.

A lot of these nuances are specific to the REST API… but if you use one of the native SDK’s like the .NET SDK, a lot of these specifics care taken care of for you. For instance, once you get an instance of the DiscoveryService, you can just call the DiscoverCapabilitiesAsync() or DiscoverCapability(string) method which will call the correct /services or /allServices method for you.