REST File Formats

From Zimbra :: Wiki

Revision as of 22:32, 17 May 2011 by Gayle (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Admin Article

Article Information

This article applies to the following ZCS versions.
  ZCS 5.0 Article  ZCS 5.0

Contents

Format Types

We are supporting a number of different "formats" for returned data. The formats we currently have implemented are:

REST file formats
Format Description
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).
vcf For exporting vcard files (vcard 3.0)
zip For exporting a set of messages (folder or search result) as a ZIP file.

Time Range Specifications

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.

Format Examples

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  

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  

and

 http://server/zimbra/home/schemers/?fmt=ifb&start=0d&end=60d  

Either format will return free/busy data for all calendars that are configured to be included in free/busy data for the next 60 days.

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.

VCF

The "vcf" formatter can export your contacts as series of vcards (vCard 3.0), or can be used to export a single contact as a vCard (to be used by the web client in a future version).

To get all your contacts as a series of vCard entries, specify "vcf" as the formatter on the GET url:

 http://server/zimbra/home/schemers/contacts.vcf  

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  

TAR

ZCS-to-ZCS Migrations » Zimbra :: Blog

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.

Verified Against: Zimbra Collaboration Suite 5.0.x Date Created: 4/25/2009
Article ID: http://wiki.zimbra.com/index.php?title=REST_File_Formats Date Modified: 05/17/2011
Personal tools