Just a little update the previous “All REST and no play…” blog entry.
It has been a while since the last blog post, so we thought it was time for an update to let people know what is in the next release, and what is still to come in a future release.
As mentioned in the last REST blog entry, we are supporting a number of different “formats” for returned data. The formats we currently have implemented are:
| atom | For generating an ATOM feed of mail messages and calendar appts. |
| csv | For exporting contacts. |
| ics | For exporting calendar appointments. See RFC 2445. |
| ifb | Calendar free/busy data. See RFC 2445. |
| native | Default formatter used to output messages and attachments in their “native” format. Used by the web client to reference attachments for downloading. |
| rss | For generating an RSS feed of mail messages and calendar appts. |
| sync | Similar to the native formatter, used by sync clients to retrieve raw message data, along with some extra meta-data in the HTTP header (tags, flags, received date). |
| zip | For exporting a set of messages (folder or search result) as a ZIP file. |
Here are some sample URLs for the various formatters.
ATOM
http://server/zimbra/home/schemers/inbox.atom
Returns an Atom feed for all messages in the inbox. If you only want unread messages as part of the feed, you could include a search query:
http://server/zimbra/home/schemers/inbox.atom?query="is:unread"
You can also request an Atom feed of a calendar folder as well:
http://server/zimbra/home/schemers/calendar.atom
Note that “calendar” is the pathname to the folder called “calendar”, it isn’t a special-cased pathname. If you had a calendar folder called “talks”, then you can access that folder via:
http://server/zimbra/home/schemers/talks.atom
When used with a calendar folder, the Atom feed will (by default) generate a feed of all appointments -/+ 7 days from the current time. To specify a different time range, you can use the start/end query parameters:
http://server/zimbra/home/schemers/calendar.atom?start=0days&end=30days
The time range can be specified in a number of different formats:
(milliseconds UTC)
MM/DD/YYYY
YYYY/MM/DD
{relative dates}
relative dates are either in the future (p/+/{not-specified}) or the past (m/-), along with a numeric value, followed by the units.
For units, everything after the first character is ignored (except for the “mi” case):
| m(onths) |
| mi(nutes) |
| d(ays) |
| w(eeks) |
| h(ours) |
| y(ears) |
Examples:
| 1day | 1 day from now |
| +2days | 2 days from now |
| p1day | 1 day from now |
| -2days | 2 days ago |
| +60mi | 60 minutes from now |
| +1week | 1 week from now |
| +6mon | 6 months from now |
| 1year | 1 year from now |
The start/end query parameters apply to the atom, ics, rss, and ifb formatters.
CSV
http://server/zimbra/home/schemers/contacts.csv
Exports all contacts in the contacts folder. If you want to export only contacts tagged “zimbra”, you can specify a query:
http://server/zimbra/home/schemers/contacts.csv?query="tag:zimbra"
This will only export contacts that are tagged with “zimbra”.
ICS
http://server/zimbra/home/schemers/calendar.ics
Will export all appointments in the calendar folder in the ICS format, suitable for import into a calendar client such as Apple’s iCal, or Mozilla’s Sunbird calendar client.
IFB
http://server/zimbra/home/schemers/calendar.ifb?start=0d&end=60d
Will export the free/busy data in the calendar folder for the next 60 days. Note that this is the free/busy data for the calendar folder only. If someone has multiple calendar folders then you’d want to use the following URL instead:
http://server/zimbra/home/schemers/?fmt=ifb&start=0d&end=60d
That URL will return free/busy data across all calendars that are configured to be included in free/busy data.
NATIVE
The native formatter is used to request raw RFC 822 messages (for example, to implement “show original”) or to down an attachment. For example, lets assume that message id 376 in my inbox is a multipart/mixed MIME message, and part 2 is an image.
The following URL (which is normally generated automatically when you are viewing your mail and click on an attachment), would download that attachment and display it in your browser:
http://server/zimbra/home/schemers/?id=376&part=2
Lets say part 3 in that same message is a word doc, you could display that via:
http://server/zimbra/home/schemers/?id=376&part=3
Finally, lets say you have the Network edition installed and want to view that same word doc as HTML instead of downloading the word doc and opening it up as an attachment. Adding “view=html” to the end of the URL will convert the word doc to HTML:
http://server/zimbra/home/schemers/?id=376&part=3&view=html
An upcoming release will expose this functionality directly in the web UI.
RSS
http://server/zimbra/home/schemers/inbox.rss
Returns an RSS feed for all messages in the inbox. All the other examples given for the Atom formatter also apply to the RSS formatter.
One further note on both the Atom and RSS formatters is that the calendar feeds provided by them currently only include the title/notes data. As soon as a more complete server-side I18N infrastructure is in place (we have been focused on the web client) the Atom/RSS feeds for calendars will be much more detailed.
SYNC
The sync formatter is similar to the native formatter, with the only exception being it adds some extra meta-data to the output for sync clients.
ZIP
The Zip formatter allows you to request a set of messages (currently only mail messages, at some point will probably allow attachments/contacts/appts as well) returned to you as a Zip file.
For example, if you want a copy of all messages in your inbox, you could use the following URL:
http://server/zimbra/home/schemers/inbox.zip
If you wanted all messages across all folders that were from Ross, you could use a query that returned only those:
http://server/zimbra/home/schemers/?fmt=zip&query="from:ross"
The zip file will consist of a set of RFC822 files, with the name of the file based on the subject of the message.
TODO
There are still a number of formatters that we’d like to add, including:
| html | For generating HTML-formatted output. For example, you could “publish” a calendar folder, and anyone with a browser can view that calendar via a browser, without needing an account to login to. |
| json | We are big fans of JSON. By default, the web client sends requests to the server via XML SOAP, but requests the results be returned in JSON, which is much more efficient to process in the browser. We are going to add a JSON formatter so you can return results in the same format. |
| micro | microformats look interesting and could potentially fit in quite nicely with our REST infrastructure. |
| text | A simple text formatter would be nice as well. Something human-readable, not necessarily human-readable. |
| xml | To go along with JSON, you should also be able to specify XML as a format. The server supports returning either XML or JSON, so this will be easy. |
Other potential formatters are ones that implement alternate client views, like a stripped down HTML/WAP formatter for mobile client access.
We need to do some work on the web client UI to expose all the functionality expressible via the REST interfaces. Maybe an “export folder/search” wizard that would ask a series of questions, and then generate the resulting URL for you automatically, at which point you could mail it and/or click on it.
We’d also like to encourage people to write their own formatters. There is a framework on the server-side for writing formatters, and it is actually quite easy. The Zip formatter, for example, is less then two pages of code.
One final note: you can specify either /zimbra/home/ or /zimbra/user/ in all the examples. We added home as a synonym for user for those cases where the account being accessed is not a really a user (for example, a marketing account).
Comments are closed.