REST-based API for Exchange ActiveSync

It’s been years since I started doing coding relating to Exchange ActiveSync out of a curiosity for troubleshooting ActiveSync, and it resulted in me coming out with my first version of the EAS MD utility for diagnosing EAS issues. Since then I’ve expanded the functionality, built an online web-based version, and I also blogged a series of posts on how to implement parts of the EAS protocol. In other words; Iโ€™ve learned a thing or two about how to get a mobile device talking to a server Smilefjes

But for a long time not much more has been happening in this space for me. Thing is, once you’ve built a utility that does what it’s supposed to do you can only do so much more before it starts to bloat. I wanted to do something more related to EAS though, but the current approach would only let me go so far.

Another challenge I’ve been having is that I get the occasional request for the source code for EAS MD. Now, a lot of the code has been published in the Exchange ActiveSync Building Blocks series as isolated parts, but the utility itself has not been properly open-sourced. There are different reasons for that, and while I’ve always wanted to help out fellow devs I haven’t gotten around to releasing it yet. (I’m happy to provide code samples, but some of the code is sort of messy.)

So, I came up with a new project aiming to learn more about EAS for myself, as well as open-sourcing the results, and hopefully creating something that benefits other people as well in the process. (I’ll let the readers decide if it’s of any actual value to other people than yours truly.)

I thought I’d take a stab at creating a RESTful EAS API.

Ehh.. Say what?

Well, you could technically say that EAS is an API itself; namely for interacting with Exchange Server. (If it feels more correct you can call my API a wrapper instead if you like.) It is however not necessarily developer friendly, and it’s not exactly built with the most current technological standards. I’m not blaming Microsoft for their design decisions mind you – they started working on it a long time ago and they made choices based on what was available at the time. They could certainly have upgraded it in later versions of Exchange Server as new shiny objects become available, but one of the good things about EAS is that it doesn’t change frequently, and maintains decent backwards compatibility. (Sure, there are minor changes from one Exchange version to the next, but not something that changes the protocol fundamentally in the way that clients needs to be rewritten from scratch.)

Imagine being able to work with Exchange in a somewhat easier manner, and not have the same restraintsโ€ฆ

When interacting with an Exchange Server through the EAS protocol you need to handle a couple of things; you need to produce XML documents for whatever you’re trying to achieve, and convert it to WBXML. When receiving something in return from Exchange you reverse the process. I’m not saying this is rocket-science, but I thought I’d give it a try simplifying this process nonetheless. Abstract away certain details you could say. Now, for an actual Exchange ActiveSync client you still need to have a database or something client-side, and might have to do integration with the host OS, and a number of other things before you end up with something an average end-user is able to use. But I’m trying to create an API – not solve everything end-to-end ๐Ÿ™‚

So, let’s say you’re trying to search the global address list for a contact called "Andreas". This is a fairly simple request, and the XML looks like this:

 <?xml version="1.0" encoding="utf-8"?>  
 <Search xmlns="Search:">  
     <Store>  
         <Name>GAL</Name>  
         <Query>andreas</Query>  
     <Options>  
        <Range>0-1</Range>  
     </Options>  
     </Store>  
 </Search>

Not so bad actually. But wouldn’t it be even easier if you didn’t have to care about this XML either? Let’s say you just do an HTTP GET against http://localhost/API/GAL?searchFor=Andreas&range=1 and get the results back nicely formatted as JSON (or XML if you prefer).

JSON sample:

 [{
"DisplayName":"EAS Web Access",
"Phone":null,
"Office":null,
"Title":null,
"Company":null,
"Alias":"easwa",
"FirstName":"EAS",
"LastName":"Web Access",
"HomePhone":null,
"MobilePhone":null,
"EmailAddress":"easwa@contoso.com",
"Picture":null,
"Status":null,
"Data":null
}]

The GAL query isn’t hard, but for instance getting a list of all contacts a user has stored has more steps to it:
– FolderSync command to get all folder ids. Parse out the folder id for "contacts".
– Sync command with a synckey value of "0" to get a new synckey.
– Sync command with the folder id of contacts, and the new synckey to get the actual contacts.

Or doing HTTP GET http://localhost/API/Contacts.

You get the picture ๐Ÿ™‚

I’m not saying it’s a bad idea to do this directly without an intermediate step like a wrapper/extra API. I’m just saying it’s an option that could be useful in scenarios where you know you want "something" from Exchange, but don’t need to have a "thick" client. Yeah, I have been thinking about whether this falls into the category "solution looking for a problem", but I’ve got nothing to lose having a crack at it anyways ๐Ÿ™‚

I’ve included a WebTestClient (available from NuGet) in the project, so you get a nice little "Test API" button to play with the API:
image

image

As for an actual application.. How about something like Outlook Web App – only using EAS instead? It could look like this:
image

Now, this web app isn’t included in the open-source parts, and there’s a couple of reasons for that:
– It’s not fit for consumption yet. While things like usernames certainly aren’t hardcoded, there’s things in the model context that needs to be sorted out. Basically it needs some tidying up. (For theming I’m probably going to rework it to use Bootstrap or something.)
– I am unsure as to how the licensing part of it would work. EAS is not free as in "you don’t have to be licensed to use it", and I’m not sure Microsoft would approve of me releasing it without a license.
– Even if I were in the clear when it comes to the licensing I haven’t decided if I want to release it. (The goal is releasing an API, not releasing a client for handling Exchange data.)

While it will be fairly evident by looking at the code that this is not a glorious 1.0 final RTM product with a bit of luck it could be the beginnings of something I hope ๐Ÿ™‚ There are things that aren’t implemented, there are bugs, there are probably lots of issues I haven’t considered. Those issues will be listed and addressed on the project site.

The project can be located at http://easweb.codeplex.com, and the license is GPLv2. If this license does not meet your needs you’re free to contact me too see if we can work something out.

Iโ€™ve also spun up a test web site in Azure letting you test the APIs Iโ€™ve done so far:
https://easweb.azurewebsites.net

Oh, and of course – do let me know if this is something that gets you excited, or you’ve got pointers as to what direction we should take this ๐Ÿ™‚

4 thoughts on “REST-based API for Exchange ActiveSync”

  1. From the API doc page, I found an API to sync emails of the “Default Inbox” folder. Is there an API to sync emails from other folders?

  2. There isn’t an API in the code currently that will let you sync other folders than the default inbox. EAS allows you to query for other folders as well, so the code can be modified to support other folders as well. (There might be some extra code to handle listing out the folders, etc. but it is possible from a protocol standpoint as long as the folder is server-based.)

    MSFT is somewhat vague on disclosing licensing details in public. I can’t say for sure whether you would need a license, and you need to sign an NDA with MSFT to ask them. It would depend on the usage scenario you’re looking to implement. In general – if you implement EAS in a product of yours, and you make money from it you will need a license ๐Ÿ™‚

    I don’t see EAS Web API itself needing a license, but your front-end and/or client apps might need it.

Leave a Reply

Your email address will not be published. Required fields are marked *

*