Revisiting the Zimbra REST API…

For years, the Zimbra Collaboration Suite (ZCS) has exposed mailbox data via REST. And lately, a few customers have asked about the Zimbra REST API (e.g. How is the API used? What methods are available? How does the Zimbra REST API compare to the Zimbra SOAP API?). So I thought it would be good to revisit the topic.

Some background: REST (REpresentational State Transfer) is an approach for building application services that make application resources available via a URL. There is more than ample information about REST out there on the web so I’ll just point you to the REST Wikipedia article for simplicity.

The Zimbra REST API is a great mechanism for reading user mailbox data and outputting that data in different formats (everything from XML-and-JSON to RSS-and-Atom to iCal-and-VCF). In addition to reading data, we’ve exposed methods to import items — like contacts and appointments — into a mailbox. This capability is very useful when performing a migration (i.e. “how do I import contacts from one system into Zimbra?”)

Here is an example of using the REST API to read mailbox data: if you want an output of messages from the “john doe” inbox folder, you call the Zimbra REST API like this:

http://localhost:7070/home/john.doe/inbox?fmt=xml

You can try this method against a Zimbra server via a browser but more commonly customers use the REST API methods from perl scripts or PHP applications…or even just from the command line using curl.

Here is an example of importing contacts into the “john doe” account: perform a POST of a CSV file to the “contacts” folder. The following command shows importing contacts using curl:

curl -{username}:{password} --upload-file /tmp/mycontacts.csv http://localhost:7070/home/john.doe/contacts?fmt=csv

That’s just a couple examples and as you can see, the REST API is a simple yet powerful mechanism for accessing mailbox data. For more information on the Zimbra REST API (i.e. information on authentication, output formats or just a list & syntax for the REST API methods), here is a link to Zimbra REST API Reference document:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimbra_REST_API_Reference

One more thing: A very common question is: “why does the SOAP API support so many more functions than the REST API?” Well, the Zimbra REST API is different (in form and function) than the Zimbra SOAP API. At a high level, it’s really an apples-to-oranges comparison. The REST API is for accessing user mailbox data, and the SOAP API is for executing functionality on the server (which can access user mailbox data and also perform account and administrative functions).

The Zimbra SOAP API is the foundational platform service that the Zimbra Web Client uses to communicate between the browser and the Zimbra server. As you can imagine, to create the rich interface experience the Zimbra Web Client delivers, the SOAP API is very complete with advanced and complex functionality, much more than the REST API. To re-create all of this complex functionality in REST API would be a challenge as well as take significant time. So as the alternative, we expose the SOAP API for direct use by our customers & partners.

But that’s another story…I’ll save the Zimbra SOAP API discussion for a different day…until then, enjoy the REST API and happy coding!