RE: ISSUE-7: Gathering requirements [Calendar API]

On 16th September Richard Tibbett wrote:
> Therefore, for the Calendar API...
> 
> 
> Key Functionality:
> 
> * Create a new calendar event
> 
> * Update an existing calendar event
> 
> * Remove an existing calendar event
> 
> * Find existing calendar events
> 
> Notes:
> 
> * An iCalendar [1] format MUST be used to represent an 'event' object
> throughout the Calendar API.
> 
> 
> Does anyone expect any more than this in the first instance of API
> requirements?

In addition, I would say...

* Give me a list of my calendars please

Oh sure, you can enter URLs in, etc, etc, but the fact is that on a
mobile form factor you want to provide the minimum configuration
possible, and this will usually come down to:

A) domain name
B) user name
C) password

Given that minimum of information, I want the device to be able to
display all of the calendars (yes, assume there can be more than one)
for that username.

Having this defined right at the start is a Good Thing, and it isn't
usually a complex item.  The list will typically be a list of URLs.


* Tell me the server capabilities please

Most specifications change over time, and it would be good to know what
capability and what version of that capability the contacted server
supports.


* Tell me (X,Y,Z) properties of the connected user please

Typically a calendar server will have properties associated with users,
such as display names, policy information around scheduling, normal
working hours, etc.


* Tell me (X,Y,Z) properties of the calendar please

The sorts of data associated with calendars might include default
timezone, preferred display colour (this is useful where the user access
the calendar from multiple devices and wants a consistent colour scheme
across all devices).


* Please send me #N changes in this calendar since ordinal change #X

Mobile devices are often disconnected, and in order to minimise
bandwidth costs through frequent downloading it would be nice to be able
to indicate exactly which set of changes should be sent to me to update
my local cache.  To be able to do this in a memory and CPU constrained
environment it is good to be able to limit the resultset, so that an
initial connection to a calendar with many years of events does not
cause the device to explode.


* Please tell me when user@example.org is available for a meeting.

Date limited enquiry is helpful for scheduling meetings.


* Please list the other calendars I may access

Sometimes free/busy enquiry is not enough and you want to know why they
are busy, or when they booked something for.


* Please tell me what time zones you know about

There are way too many problems with timezone inconsistencies.  If we
let the servers control them then we are reducing complexity and
bandwidth in one fell swoop.  If the servers get them all from a
centralised service, which is slowly being implemented, we're ultimately
even better off.


Notes:
* Sometimes the iCalendar data might be passed around inside XML CDATA
elements.  This is OK.

* Events are not always events (VEVENT): sometimes they are tasks
(VTODO) or notes (VJOURNAL).  These other possibilities are also useful,
and often not difficult to support if people are aware of them at the
start.

* From what I understand of the purpose of this specification the above
implies that read/write access to the data, and read-only access to the
metadata is an appropriate mix.

* A lot of the above is informed by an understanding of CalDAV and the
proposed scheduling extensions to CalDAV and a few other bits and pieces
related to that, but I've endeavoured not to replicate some of the more
arcane and egregious parts of that.  It certainly is not a 1:1 mapping,
or even a 1:n or n:1 mapping.


> Does anyone see the need to break down the key
> functionality to medium and low level requirements at the beginning or
> during the API creation phase?
> 
> Perhaps others have different views on the best process to use. For
> example, an alternative proposal could be to begin with use cases and
> work out the required functionality from there or to look at existing
> implementations and identify the shared core functionality as the
basis
> for any given API (FYI, the Calendar API requirements included above
are
> a loose paraphrasing of BONDI Calendar API requirements).
> 

I'm a fan of throwing in all possible requirements that people can come
up with in the broadest wishlist set ever, and then reviewing them for
sanity, mergability, simplicity and importance before coming up with a
dedicated core to attack first.

I'll be at the Calendaring & Scheduling Consortium meeting in Cupertino
next week, so if anyone in that area wants to meet up feel free to get
in touch.

Cheers,
                                        Andrew McMillan.

------------------------------------------------------------------------
http://andrew.mcmillan.net.nz/                     Porirua, New Zealand
Twitter: _karora                                  Phone: +64(272)DEBIAN
   Increased knowledge will help you now.  Have mate's phone bugged.
------------------------------------------------------------------------