Versioning in the Office 365 Reporting web service

Article
09/21/2016

To ensure future compatibility with existing Office 365 Reporting web service clients, the web service accepts an X-RWS-Version HTTP header, or an rws-version URI parameter. The ODATA service also has version-compatibility headers that your application should use. At this time (February, 2013) the only valid service version for this feature is 2013-V1. This topic describes how to work with service and ODATA data service versions.

Applies to: Office 365

Office 365 Reporting web service versions

Online services such as Office 365 receive frequent updates that add functionality and fix issues. Office 365 uses service version identifiers in the form YEAR-V#. YEAR is the calendar year in which the release becomes generally available to most subscribers. The # indicates the year's release number. As of March 2013, the mainstream in-service version is 2013-V1. The previous version was 2012-V1; however, the Office 365 Reporting web service was not generally available in that service version. Requests to use the 2012-V1 version will return an error containing <Message>The version specified in the request is unsupported.</Message>.

To help ensure client compatibility with future service versions, applications should specify that requests to, and responses from, the Reporting web service be handled according to a specific service version. If the application does not request a specific service version, the most recent service version is assumed. Your application should always request the service version it was designed to work with so it can continue functioning properly as the service is updated. After you've tested your application against an updated service version, you can update the version that the application requests.

Requesting a specific service version

The Reporting web service provides two ways to request a specific service version. Applications can use the X-RWS-Version header in the HTTP request, or it can provide the rws-version URI parameter.

The X-RWS-Version HTTP request header looks like this over the wire: X-RWS-Version:2013-V1.

The rws-version URI parameter looks like this in practice: rws-version=2013-V1. The following example requests that service version 2013-V1 be used to process the StaleMailbox report.

https://reports.office365.com/ecp/reportingwebservice/reporting.svc/StaleMailbox?rws-version=2013-V1&
  $select=ActiveMailboxes,Date,InactiveMailboxes31To60Days,InactiveMailboxes61To90Days,InactiveMailboxes91To1460Days&
  $top=1&
  $format=Atom

Important

Do not provide both the HTTP header and the URI parameter in the same report request. When the Reporting web service encounters both, even if they are for the same service version, it will return the following error.

<?xml version="1.0" encoding="utf-8"?>
<ServiceFault xmlns="http://schemas.datacontract.org/2004/07/Microsoft.Exchange.Management.ReportingWebService" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <ErrorCode />
  <Message>The API version is specified in both request URL and header.</Message>
</ServiceFault>

To decide how to indicate the service version, consider your code architecture. If your application only needs to access one version, use the HTTP request header. If your application uses different service versions for different reports, and creating the HttpRequest is done generically for all reports regardless of service version, use the URI parameter. Whatever method you choose, do not use both.

X-RWS-Version header returned by the web service

All successful HTTP responses, and most unsuccessful responses, that are returned to your client application include the X-RWS-Version header. That header will specify the service version level that applies to the results. When the application doesn't specify any particular version, the Reporting web service returns the most current service version. When the application does specify a version, if that version is available, the report returns the requested service version to confirm that the application's request can be serviced in the requested version.

ODATA data service versions

The ODATA infrastructure on which the Office 365 Reporting web service is built also has versions that are updated from time to time and will likely show up in the Reporting web service at some point. There are two headers: the DataServiceVersion that specifies the preferred ODATA version, and the MaxDataServiceVersion that specifies a version which the service should not exceed. These headers also help ensure continued reliability for systems tested against previous service version. For more information, see the section on protocol versioning (section 7) in the ODATA Overview page.

DataServiceVersion HTTP header

The DataServiceVersion header instructs the ODATA request handler and data formatting to use the indicated DataServiceVersion. As of February, 2012, the appropriate service version is 2.0. A DataServiceVersion header is returned with the report response, so that the application can confirm that the version in use is compatible.

MaxDataServiceVersion HTTP Header

The MaxDataServiceVersion instructs the Reporting web service not to use any version higher than the one supplied. For example, if the current version is 2.0, and you don't want to allow the next major version (3.0) to be used, specify a header with MaxDataServiveVersion:2.99.

Office 365 Reporting web service preferred ODATA versions

To ensure greater compatibility with ODATA clients, the Reporting web service uses two different DataServiceVersion values depending on what is being requested:

Reporting.svc service description document uses ODATA DataServiceVersion 1.0.
All other reports use ODATA DataServiceVersion 2.0.

Example

The following example demonstrates how to add the headers described in this topic to an HttpWebRequest. The headers can be added in any order but you should not include more than one copy of each header.

  //
  // First, create the web request object to add the versioning information and other headers to.  
  HttpWebRequest request = 
    (HttpWebRequest)HttpWebRequest.Create("https://reports.office365.com/ecp/reportingwebservice/reporting.svc");
  request.Method = "GET";
  //
  // This header specifies the ODATA provider's minimum version. Because we use $select in later queries,
  // we need to have at least ODATA2. And since we don't (yet) support anything higher than 2.0, we'll give
  // that as a maximum also.
  request.Headers.Add("DataServiceVersion", "2.0");
  request.Headers.Add("MaxDataServiceVersion", "2.0");
  //
  // Add the RWS language header.
  request.Headers.Add("Accept-Language","EN-US");
  //
  // Add the RWS service version section header.
  request.Headers.Add("X-RWS-Version","2013-V1");
  //
  // For authentication reasons, avoid redirecting the HTTPS request.
  request.AllowAutoRedirect = false;
  //
  // The "simple" way to get the Basic-authentication credentials: 
  request.Credentials = new NetworkCredential(userNameEntered, passwordEntered);
  //
  // Make the Web call here. This is normally done using asynchronous methods so that the application
  // interface is not blocked waiting for the service to respond.
  HttpWebResponse response = (HttpWebResponse)request.GetResponse();