One of the things we are working on for an upcoming release is REST interfaces into all our content. If you aren’t familiar with REST I’d just suggest reading Building Web Services the REST Way.
Today, within the Zimbra Collaboration Suite we have a number of different server-side URLs that our client accesses to download an attachment, export contacts as CSV, export a calendar as an ICS, file etc. We are also adding sharing (what would collaboration be without sharing, after all) of calendars, contacts, etc. Not only within a particular Zimbra community, but between Zimbra communities and the public at large.
In order to facilitate this, we are coming up with a clean, consistent URL interface to all our resources. The best way to describe this is with some examples.
Lets say I want access to my calendar folder from within iCal. The URL would look like:
http://server/zimbra/user/roland/calendar
The default format on calendar folders is ICS, so no need to specify the format.
Lets say I want to export my contacts folder so I can import them into another account:
http://server/zimbra/user/roland/contacts
Contact folders have a default type of CSV, so like calendars, no need to specify the format.
How about an RSS feed of unread messages in my inbox:
http://server/zimbra/user/roland/inbox.rss?query="is:unread"
By specifying an extension of “.rss” on the inbox folder, the server will automatically generate an RSS feed on it. Adding the “query” parameter lets me further refine what gets returned. You can also specify “?fmt=rss” instead of using the “.rss” extension if you’d like.
Lets do something a little more interesting. How about a zip file containing all messages in my talks/ajax folder:
http://server/zimbra/user/roland/talks/ajax.zip
The server zips them all up and returns the zip file.
Another interesting example is say you have created a public calendar that you want to share with everyone. Once you have granted access to the calendar, it is up to the consumer to chose what format they want to view it in:
http://server/zimbra/user/roland/calendar/talks.ics
http://server/zimbra/user/roland/calendar/talks.html?view=month
http://server/zimbra/user/roland/calendar/talks.atom
http://server/zimbra/user/roland/calendar/talks.xml
http://server/zimbra/user/roland/calendar/talks.txt
How about accessing another user’s calendar/folder? Once they grant you access, you can use the same exact syntax:
http://server/zimbra/user/janie/holidays.ics
One last interesting example to leave you with. Lets say you have a friend at widgets.com who you know is running Zimbra and who has shared their calendar with you, but you don’t know the name of their public Zimbra server. As long as they publish some DNS SRV records for _zimbra._tcp.widgets.com, then you can access it directly from your Zimbra without needing to know his server’s address:
http://server/zimbra/user/friend@widgets.com/calendar
on November 11th, 2005 at 1:48 am
Would it not be more restful to reuse the same url, for example, ‘http://server/zimbra/user/roland/calendar/talks’ to get your calendar and to set the Accept header in the get message to the mime type of the representation required?
on November 11th, 2005 at 1:55 am
awesome, thanks.
on November 13th, 2005 at 2:23 am
These URLs are intended for human consumption, and I’d hate to tell our office admin she has to write a perl script to set accept headers
I forgot to mention that you can also put the format in a query param like so:
http://server/zimbra/user/roland/calendar/talks?fmt=ics
http://server/zimbra/user/roland/calendar/talks?fmt=atom
which makes the path itself not change.
thanks, roland
on April 12th, 2007 at 2:03 am
You wrote in the “update” of the blog entry:
“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.”
I’d like to write my own formatter to save mails but i didn’t find the framework. Could you be more precise about where I can find it please?