CALCONNECT DOCUMENT CD1011
Type: Proposal
Title: CalWS-Rest - Restful Web Services Protocol for Calendaring
Version: 1.0.1
Date: 2012-02-22
Status: Published
Source: TC XML
This document was editorially updated to ensure synchronization with the OASIS
WS-Calendar publication of CalWS-SOAP as V1.0 for public review and contains
the same content..
This document is copyright ©2012 by The Calendaring and Scheduling
Consortium and is licensed under the Creative Commons 3.0 Unported LIcense:
http://creativecommons.org/licenses/by/3.0/.
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 1 of 37
CalWSRest - Restful Web service protocol for calendaring
Version 1.0.1
Working Draft 05
17 February 2012
Technical Committee:
CalConnect TC-XML
Chair:
Michael Douglass (douglm@rpi.edu) Rensselaer Polytechnic Institute
Editor:
Michael Douglass (douglm@rpi.edu) Rensselaer Polytechnic Institute
Related work:
This specification is related to:
WS-Calendar Version 1.0. Latest version.
http://docs.oasis-open.org/ws-calendar/ws-calendar/v1.0/ws-calendar-1.0-spec.html
Abstract:
Summary of the technical purpose of the document.
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 2 of 37
Table of Contents
1 Introduction ........................................................................................................................................... 5
1.1 Terminology ........................................................................................................................................ 5
1.2 Normative References ........................................................................................................................ 5
1.3 Non-Normative References ................................................................................................................ 5
1.4 Namespace ......................................................................................................................................... 5
2 Calendar Services ................................................................................................................................ 7
2.1 Overview of the protocol ..................................................................................................................... 7
2.1.1 Calendar Object Resources ........................................................................................................ 7
2.1.2 Timezone information .................................................................................................................. 7
2.1.3 Issues not addressed by this specification. ................................................................................. 8
2.1.3.1 Access Control ..................................................................................................................................... 8
2.1.3.2 Provisioning ......................................................................................................................................... 8
2.1.3.3 Copy/Move ........................................................................................................................................... 8
2.1.3.4 Creating Collections ............................................................................................................................. 8
2.1.3.5 Retrieving collections ........................................................................................................................... 8
2.1.3.6 Setting service and resource properties. .............................................................................................. 8
2.1.4 CalWS Glossary .......................................................................................................................... 8
2.1.4.1 Hrefs .................................................................................................................................................... 8
2.1.4.2 Calendar Object Resource ................................................................................................................... 8
2.1.4.3 Calendar Collection .............................................................................................................................. 8
2.1.4.4 Scheduling Calendar Collection ........................................................................................................... 9
2.1.4.5 Principal Home..................................................................................................................................... 9
2.2 Error conditions ................................................................................................................................... 9
2.2.1 Example: error with CalDAV error condition ............................................................................... 9
3 Properties and link relations ............................................................................................................... 10
3.1 Property and relation-type URIs ....................................................................................................... 10
3.2 supported-features property. ............................................................................................................ 10
3.3 max-attendees-per-instance ............................................................................................................. 10
3.4 max-date-time ................................................................................................................................... 10
3.5 max-instances ................................................................................................................................... 10
3.6 max-resource-size ............................................................................................................................ 10
3.7 min-date-time .................................................................................................................................... 11
3.8 description......................................................................................................................................... 11
3.9 timezone-service relation. ................................................................................................................. 11
3.10 principal-home relation. .................................................................................................................. 11
3.11 current-principal-freebusy relation. ................................................................................................. 11
3.12 principal-freebusy relation............................................................................................................... 11
3.13 child-collection relation. .................................................................................................................. 11
3.14 created link property ....................................................................................................................... 12
3.15 last-modified property ..................................................................................................................... 12
3.16 displayname property ..................................................................................................................... 12
3.17 timezone property ........................................................................................................................... 12
3.18 owner property ................................................................................................................................ 12
3.19 collection link property .................................................................................................................... 12
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 3 of 37
3.20 calendar-collection link property ..................................................................................................... 12
3.21 calWS:privilege-set XML element ................................................................................................... 13
4 Retrieving Collection and Service Properties ..................................................................................... 14
4.1 Request parameters ......................................................................................................................... 14
4.2 Responses: ....................................................................................................................................... 14
4.3 Example - retrieving server properties: ............................................................................................. 14
5 Creating Calendar Object Resources................................................................................................. 16
5.1 Request parameters ......................................................................................................................... 16
5.2 Responses: ....................................................................................................................................... 16
5.3 Preconditions for Calendar Object Creation ..................................................................................... 16
5.4 Example - successful POST: ............................................................................................................ 17
5.5 Example - unsuccessful POST: ........................................................................................................ 17
6 Retrieving resources........................................................................................................................... 18
6.1 Request parameters ......................................................................................................................... 18
6.2 Responses: ....................................................................................................................................... 18
6.3 Example - successful fetch: .............................................................................................................. 18
6.4 Example - unsuccessful fetch: .......................................................................................................... 18
7 Updating resources ............................................................................................................................ 19
7.1 Responses: ....................................................................................................................................... 19
8 Deletion of resources.......................................................................................................................... 21
8.1 Delete for Collections ........................................................................................................................ 21
8.2 Responses: ....................................................................................................................................... 21
9 Querying calendar resources ............................................................................................................. 22
9.1 Limiting data returned ....................................................................................................................... 22
9.2 Pre/postconditions for calendar queries ........................................................................................... 22
9.3 Example: time range limited retrieval ............................................................................................... 22
10 Free-busy queries............................................................................................................................... 27
10.1 ACCEPT header ............................................................................................................................. 27
10.2 URL Query Parameters .................................................................................................................. 27
10.2.1 start .......................................................................................................................................... 27
10.2.2 end ........................................................................................................................................... 28
10.2.3 period ....................................................................................................................................... 28
10.2.4 account .................................................................................................................................... 28
10.3 URL parameters - notes ................................................................................................................. 28
10.4 HTTP Operations ............................................................................................................................ 28
10.5 Response Codes ............................................................................................................................ 28
10.6 Examples ........................................................................................................................................ 29
11 Conformance ...................................................................................................................................... 32
Appendix A. Acknowledgments ............................................................................................................. 33
Appendix B. An Introduction to Internet Calendaring ............................................................................ 34
B.1 icalendar ........................................................................................................................................... 34
B.1.1 History ....................................................................................................................................... 34
B.1.2 Data model ................................................................................................................................ 34
B.1.3 Scheduling ................................................................................................................................ 35
B.1.4 Extensibility ............................................................................................................................... 35
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 4 of 37
B.2 Calendar data access and exchange protocols ............................................................................... 35
B.2.1 Internet Calendar Subscriptions................................................................................................ 35
B.2.2 CalDAV ..................................................................................................................................... 35
B.2.3 ActiveSync/SyncML .................................................................................................................. 36
B.2.4 CalWS ....................................................................................................................................... 36
B.2.5 iSchedule .................................................................................................................................. 36
B.3 References ....................................................................................................................................... 36
Appendix C. Revision History ................................................................................................................ 37
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 5 of 37
1 Introduction
1
The CalWS REST protocol is built upon and makes the same assumptions about structure as the CalDAV
2
protocol defined in [RFC 4791] and related specifications. It does NOT require nor assume the WebDAV
3
nor CalDAV protocol.
4
Calendar resources, for example events and tasks are stored as named resources (files) inside special
5
collections (folders) known as "Calendar Collections".
6
This specification can be looked upon as a layer built on top of CalDAV and defines the basic operations
7
which allow creation, retrieval, update and deletion. In addition, query and freebusy operations are
8
defined to allow efficient, partial retrieval of calendar data.
9
This does not mean that a CalWS service must be built on CalDAV, merely that a degree of conformity is
10
established such that services built in that manner do not have a significant mismatch. It is assumed that
11
some CalWS REST services will be built without any CalDAV support.
12
1.1 Terminology
13
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD
14
NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described
15
in [RFC2119].
16
1.2 Normative References
17
[RFC2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels,
18
http://www.ietf.org/rfc/rfc2119.txt, IETF RFC 2119, March 1997.
19
[RFC4791] C. Daboo, B. Desruisseaux, L. Dusseault, Calendaring Extensions to WebDAV
20
(CalDAV), http://www.ietf.org/RFC/RFC4791.txt, IETF RFC4791, March 1997.
21
[WS-Calendar] WS-Calendar Version 1.0. 19 January 2011. OASIS Committee Specification
22
http://docs.oasis-open.org/ws-calendar/ws-calendar-spec/v1.0/cs01/ws-calendar-
23
spec-v1.0-cs01.pdf.
24
[XRD] Extensible Resource Descriptor (XRD) Version 1.0, 1 November 2010, OASIS
25
Standard, http://docs.oasis-open.org/xri/xrd/v1.0/os/xrd-1.0-os.xml
26
1.3 Non-Normative References
27
REST T Fielding, Architectural Styles and the Design of Network-based Software
28
Architectures, http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm.
29
30
1.4 Namespace
31
XML namespaces and prefixes used in this standard:
32
Table 1 1: XML Namespaces in this standard
33
Prefix
Namespace
xcal
urn:ietf:params:xml:ns:icalendar-2.0
calWS
http://docs.oasis-open.org/ws-calendar/ns/REST
xrd
http://docs.oasis-open.org/ns/xri/xrd-1.0
34
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 6 of 37
35
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 7 of 37
2 Calendar Services
36
The Service interactions are built upon and make the same assumptions about structure as the CalDAV
37
protocol defined in [RFC4791] and related specifications. It does NOT require nor assume the WebDAV
38
nor CalDAV protocol but does make use of some of the same elements and structures in the CalDAV
39
XML namespace.
40
Calendar resources, for example events and tasks are stored as named resources (files) inside special
41
collections (folders) known as "Calendar Collections".
42
These services can be looked upon as a layer built on top of CalDAV and defines the basic operations
43
which allow creation, retrieval, update and deletion. In addition, query, and free-busy operations are
44
defined to allow efficient, partial retrieval of calendar data.
45
These services assume a degree of conformity with CalDAV is established such that services built in that
46
manner do not have a significant mismatch. It is assumed that some WS-Calendar services will be built
47
without any CalDAV support.
48
2.1 Overview of the protocol
49
The protocol is an HTTP based RESTfull protocol using a limited set of methods. Each request may be
50
followed by a response containing status information.
51
The following methods are specified in the protocol description, PUT, POST, GET, DELETE. To avoid
52
various issues with certain methods being blocked clients may use the X-HTTP-Method-Override: header
53
to specify the intended operation. Servers SHOULD behave as if the named method was used.
54
POST /user/fred/calendar/ HTTP/1.1
55
...
56
X-HTTP-Method-Override: PUT
57
Properties
58
A service or resource will have a number of properties which describe the current state of that service or
59
resource. These properties are accessed through a GET on the target resource or service with an
60
ACCEPT header specifying application/xrd+xml. See Section 2.1.3.6
61
The following operations are defined by this specification:
62
Retrieval and update of service and resource properties
63
Creation of a calendar object
64
Retrieval of a calendar object
65
Update of a calendar object
66
Deletion of a calendar object
67
Query
68
Free-busy query
69
2.1.1 Calendar Object Resources
70
The same restrictions apply to Calendar Object Resources as specified in CalDAV [RFC4791] section
71
4.2. An additional constraint for CalWS is that no timezone specifications are transferred.
72
2.1.2 Timezone information
73
It is assumed that the client and server each have access to a full set of up to date timezone information.
74
Timezones will be referenced by a timezone identifier from the full set of Olson data together with a set of
75
well-known aliases defined [TZDB]. CalWS services may advertise themselves as timezone servers
76
through the server properties object.
77
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 8 of 37
2.1.3 Issues not addressed by this specification.
78
A number of issues are not addressed by this version of the specification, either because they should be
79
addressed elsewhere or will be addressed at some later date.
80
2.1.3.1 Access Control
81
It is assumed that the targeted server will set an appropriate level of access based on authentication. This
82
specification will not attempt to address the issues of sharing or Access Control Lists (ACLs).
83
2.1.3.2 Provisioning
84
The protocol will not provide any explicit provisioning operations. If it is possible to authenticate or
85
address a principal's calendar resources then they MUST be automatically created if necessary or
86
appropriate
87
2.1.3.3 Copy/Move
88
These operations are not yet defined for this version of the CalWS protocol. Both operations raise a
89
number of issues. In particular implementing a move operation through a series of retrievals, insertions
90
and deletions may cause undesirable side-effects. Both these operations will be defined in a later version
91
of this specification.
92
2.1.3.4 Creating Collections
93
We will not address the issue of creating collections within the address space. The initial set is created by
94
provisioning.
95
2.1.3.5 Retrieving collections
96
This operation is currently undefined. A GET on a collection may fail or return a complete calendar object
97
representing the collection.
98
2.1.3.6 Setting service and resource properties.
99
These operations are not defined in this version of the specification. In the future it will be possible to
100
define or set the properties for the service or resources within the service.
101
2.1.4 CalWS Glossary
102
2.1.4.1 Hrefs
103
An href is a URI reference to a resource, for example
104
"http://example.org/user/fred/calendar/event1.ics".
105
The URL above reflects a possible structure for a calendar server. All URLs should be absolute or path-
106
absolute following the rules defined in Error! Reference source not found. Section 8.3.
107
2.1.4.2 Calendar Object Resource
108
A calendar object resource is an event, meeting or a task. Attachments are resources but NOT calendar
109
object resources. An event or task with overrides is a single calendar resource entity.
110
2.1.4.3 Calendar Collection
111
A folder only allowed to contain calendar object resources.
112
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 9 of 37
2.1.4.4 Scheduling Calendar Collection
113
A folder only allowed to contain calendar resources which is also used for scheduling operations.
114
Scheduling events placed in such a collection will trigger implicit scheduling activity on the server.
115
2.1.4.5 Principal Home
116
The collection under which all the resources for a given principal are stored. For example, for principal
117
"fred" the principal home might be "/user/fred/"
118
2.2 Error conditions
119
Each operation on the calendar system has a number of pre-conditions and post-conditions that apply.
120
A "precondition" for a method describes the state of the server that must be true for that method to be
121
performed. A "post-condition" of a method describes the state of the server that must be true after that
122
method has been completed. Any violation of these conditions will result in an error response in the form
123
of a CalWS XML error element containing the violated condition and an optional description. \
124
Each method specification defines the preconditions that must be satisfied before the method can
125
succeed. A number of post-conditions are generally specified which define the state that must exist after
126
the execution of the operation. Preconditions and post-conditions are defined as error elements in the
127
CalWS XML namespace.
128
2.2.1 Example: error with CalDAV error condition
129
<?xml version="1.0" encoding="utf-8"
130
xmlns:CW="Error! Reference source not found.""
131
xmlns:C="http://docs.oasis-open.org/ws-calendar/ns/REST" ?>
132
<CW:error>
133
<C:supported-filter>
134
<C:prop-filter name="X-ABC-GUID"/>
135
</C:supported-filter>
136
<CW:description>Unknown property </CW:description>
137
</CW:error>
138
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 10 of 37
3 Properties and link relations
139
3.1 Property and relation-type URIs
140
In the XRD entity returned properties and related services and entities are defined by absolute URIs
141
which correspond to the extended relation type defined in [web linking] Section 4.2. These URIs do NOT
142
correspond to any real entity on the server and clients should not attempt to retrieve any data at that
143
target.
144
Certain of these property URIs correspond to CalDAV preconditions. Each URL is prefixed by the CalWS
145
relations and properties namespace http://docs.oasis-open.org/ws-calendar/ns/REST/. Those properties
146
which correspond to CalDAV properties have the additional path element "caldav/", for example
147
http://docs.oasis-open.org/ws-calendar/ns/REST/supported-calendar-data
148
corresponds to
149
CalDAV:supported-calendar-data
150
In addition to those CalDAV properties, the CalWS specification defines a number of other properties and
151
link relations with the URI prefix of http://docs.oasis-open.org/ws-calendar/ns/REST.
152
3.2 supported-features property.
153
http://docs.oasis-open.org/ws-calendar/ns/REST/supported-features
154
This property defines the features supported by the target. All resources contained and managed by the
155
service should return this property. The value is a comma separated list containing one or more of the
156
following
157
calendar-access - the service supports all MUST requirements in this specification
158
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/supported-
159
features"
160
>calendar-access</Property>
161
3.3 max-attendees-per-instance
162
http://docs.oasis-open.org/ws-calendar/ns/REST/max-attendees-per-instance
163
Defines the maximum number of attendees allowed per event or task.
164
3.4 max-date-time
165
http://docs.oasis-open.org/ws-calendar/ns/REST/max-date-time
166
Defines the maximum date/time allowed on an event or task
167
3.5 max-instances
168
http://docs.oasis-open.org/ws-calendar/ns/REST/max-instances
169
Defines the maximum number of instances allowed per event or task
170
3.6 max-resource-size
171
http://docs.oasis-open.org/ws-calendar/ns/REST/max-resource-size
172
Provides a numeric value indicating the maximum size of a resource in octets that the server is willing to
173
accept when a calendar object resource is stored in a calendar collection.
174
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 11 of 37
3.7 min-date-time
175
http://docs.oasis-open.org/ws-calendar/ns/REST/min-date-time
176
Provides a DATE-TIME value indicating the earliest date and time (in UTC) that the server is willing to
177
accept for any DATE or DATE-TIME value in a calendar object resource stored in a calendar collection.
178
3.8 description
179
http://docs.oasis-open.org/ws-calendar/ns/REST/description
180
Provides some descriptive text for the targeted collection.
181
3.9 timezone-service relation.
182
http://docs.oasis-open.org/ws-calendar/ns/REST/timezone-service
183
The location of a timezone service used to retrieve timezone information and specifications. This may be
184
an absolute URL referencing some other service or a relative URL if the current server also provides a
185
timezone service.
186
<Link rel="http://docs.oasis-open.org/ws-calendar/ns/REST/timezone-service"
187
href="http://example.com/tz" />
188
3.10 principal-home relation.
189
http://docs.oasis-open.org/ws-calendar/ns/REST/principal-home
190
Provides the URL to the user home for the currently authenticated principal.
191
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/principal-home"
192
href="http://example.com/user/fred" />
193
3.11 current-principal-freebusy relation.
194
http://docs.oasis-open.org/ws-calendar/ns/REST/current-principal-freebusy
195
Provides the URL to use as a target for freebusy requests for the current authenticated principal.
196
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/current-principal-freebusy"
197
href="http://example.com/freebusy/user/fred" />
198
3.12 principal-freebusy relation.
199
http://docs.oasis-open.org/ws-calendar/ns/REST/principal-freebusy
200
Provides the URL to use as a target for freebusy requests for a different principal.
201
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/principal-freebusy"
202
href="http://example.com/freebusy" />
203
3.13 child-collection relation.
204
http://docs.oasis-open.org/ws-calendar/ns/REST/child-collection
205
Provides information about a child collections for the target. The href attribute gives the URI of the
206
collection. The element should only have CalWS child elements giving the type of the collection, that is
207
the calWS:collection link property and the CalWS-calendar-collection link property. This allows clients to
208
determine the structure of a hierarchical system by targeting each of the child collections in turn.
209
The xrd:title child element of the link element provides a description for the child-collection.
210
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/child-collection"
211
href="http://example.com/calWS/user/fred/calendar">
212
<Title xml:lang="en">Calendar</Title>
213
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/collection"
214
xsi:nil="true" />
215
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 12 of 37
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/calendar-
216
collection"
217
xsi:nil="true" />
218
</Link>
219
3.14 created link property
220
http://docs.oasis-open.org/ws-calendar/ns/REST/created
221
Appears within a link relation describing collections or entities. The value is a date-time as defined in
222
[WS-Calendar] Section 5.6
223
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/created"
224
>1985-04-12T23:20:50.52Z</Property>
225
3.15 last-modified property
226
http://docs.oasis-open.org/ws-calendar/ns/REST/last-modified
227
Appears within an xrd object describing collections or entities. The value is the same format as would
228
appear in the Last-Modified header and is defined in [RFC2616], Section 3.3.1
229
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/last-modified"
230
>Mon, 12 Jan 1998 09:25:56 GMT</Property>
231
3.16 displayname property
232
http://docs.oasis-open.org/ws-calendar/ns/REST/displayname
233
Appears within an xrd object describing collections or entities. The value is a localized name for the entity
234
or collection.
235
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/displayname"
236
>My Calendar</Property>
237
3.17 timezone property
238
http://docs.oasis-open.org/ws-calendar/ns/REST/timezone
239
Appears within an xrd object describing collections. The value is a text timezone identifier.
240
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/timezone"
241
>America/New_York</Property>
242
3.18 owner property
243
http://docs.oasis-open.org/ws-calendar/ns/REST/owner
244
Appears within an xrd object describing collections or entities. The value is a server specific uri.
245
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/owner"
246
>/principals/users/mike</Property>
247
3.19 collection link property
248
http://docs.oasis-open.org/ws-calendar/ns/REST/collection
249
Appears within a link relation describing collections or entities. The property takes no value and indicates
250
that this child element is a collection.
251
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/collection"
252
xsi:nil="true" />
253
3.20 calendar-collection link property
254
http://docs.oasis-open.org/ws-calendar/ns/REST/calendar-collection
255
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 13 of 37
Appears within a link relation describing collections or entities. The property takes no value and indicates
256
that this child element is a calendar collection.
257
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/calendar-
258
collection"
259
xsi:nil="true" />
260
3.21 calWS:privilege-set XML element
261
http://docs.oasis-open.org/ws-calendar/ns/REST/privilege-set
262
Appears within a link relation describing collections or entities and specifies the set of privileges allowed
263
to the current authenticated principal for that collection or entity.
264
<!ELEMENT calWS:privilege-set (calWS:privilege*)>
265
<!ELEMENT calWS:privilege ANY>
266
Each privilege element defines a privilege or access right. The following set is currently defined
267
calWS: Read - current principal has read access
268
calWS: Write - current principal has write access
269
<calWS:privilege-set>
270
<calWS:privilege><calWS:read></calWS:privilege>
271
<calWS:privilege><calWS:write></calWS:privilege>
272
</calWS:privilege-set>
273
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 14 of 37
4 Retrieving Collection and Service Properties
274
Properties, related services and locations are obtained from the service or from service resources in the
275
form of an XRD document as defined by [XRD-1.0].
276
Given the URL of a CalWS service a client retrieves the service XRD document through a GET on the
277
service URL with an ACCEPT header specifying application/xrd+xml.
278
Retrieving resource properties is identical to obtaining service properties, that is, execute a GET on the
279
target URL with an ACCEPT header specifying application/xrd+xml.
280
The service properties define the global limits and defaults. Any properties defined on collections within
281
the service hierarchy override those service defaults. The service may choose to prevent such overriding
282
of defaults and limits when appropriate.
283
4.1 Request parameters
284
None
285
4.2 Responses:
286
200: OK
287
403: Forbidden
288
404: Not found
289
4.3 Example - retrieving server properties:
290
>>Request
291
292
GET / HTTP/1.1
293
Host: example.com
294
ACCEPT:application/xrd+xml
295
296
>>Response
297
<XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0"
298
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
299
<Expires>1970-01-01T00:00:00Z</Expires>
300
<Subject>http://example.com/calWS</Subject>
301
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/created"
302
>1970-01-01</Property>
303
304
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/timezone-
305
service"
306
href="http://example.com/tz" />
307
308
<calWS:privilege-set>
309
<calWS:privilege><calWS:read></calWS:privilege>
310
</calWS:privilege-set>
311
312
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/principal-home"
313
type="collection"
314
href="http://example.com/calWS/user/fred">
315
<Title xml:lang="en">Fred's calendar home</Title>
316
</Link>
317
318
<Link rel=" http://docs.oasis-open.org/ws-calendar/ns/REST/child-
319
collection"
320
type="calendar,scheduling"
321
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 15 of 37
href="http://example.com/calWS/user/fred/calendar">
322
<Title xml:lang="en">Calendar</Title>
323
</Link>
324
325
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/max-
326
instances"
327
>1000</Property>
328
329
<Property type=" http://docs.oasis-open.org/ws-calendar/ns/REST/max-
330
attendees-per-instance"
331
>100</Property>
332
333
</XRD>
334
335
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 16 of 37
5 Creating Calendar Object Resources
336
Creating calendar object resources is carried out by a POST on the parent collection. The body of the
337
request will contain the resource being created. The request parameter "action=create" indicates this
338
POST is a create. The location header of the response gives the URL of the newly created object.
339
5.1 Request parameters
340
action=create
341
5.2 Responses:
342
201: created
343
403: Forbidden - no access
344
5.3 Preconditions for Calendar Object Creation
345
calWS:target-exists: The target of a PUT must exist. Use POST to create entities and PUT to
346
update them.
347
calWS:not-calendar-data: The resource submitted in the PUT request, or targeted by a COPY or
348
MOVE request, MUST be a supported media type (i.e., iCalendar) for calendar object resources;
349
calWS:invalid-calendar-data: The resource submitted in the PUT request, or targeted by a COPY
350
or MOVE request, MUST be valid data for the media type being specified (i.e., MUST contain valid
351
iCalendar data);
352
calWS:invalid-calendar-object-resource: The resource submitted in the PUT request, or targeted
353
by a COPY or MOVE request, MUST obey all restrictions specified in Calendar Object Resources
354
(e.g., calendar object resources MUST NOT contain more than one type of calendar component,
355
calendar object resources MUST NOT specify the iCalendar METHOD property, etc.);
356
calWS:unsupported-calendar-component: The resource submitted in the PUT request, or
357
targeted by a COPY or MOVE request, MUST contain a type of calendar component that is
358
supported in the targeted calendar collection;
359
calWS:uid-conflict: The resource submitted in the PUT request, or targeted by a COPY or MOVE
360
request, MUST NOT specify an iCalendar UID property value already in use in the targeted
361
calendar collection or overwrite an existing calendar object resource with one that has a different
362
UID property value. Servers SHOULD report the URL of the resource that is already making use of
363
the same UID property value in the calWS:href element
364
<!ELEMENT uid-conflict (calWS:href)>
365
calWS:invalid-calendar-collection-location: In a COPY or MOVE request, when the Request-URI
366
is a calendar collection, the Destination-URI MUST identify a location where a calendar collection
367
can be created;
368
calWS:exceeds-max-resource-size: The resource submitted in the PUT request, or targeted by a
369
COPY or MOVE request, MUST have an octet size less than or equal to the value of the
370
CalDAV:max-resource-size property value on the calendar collection where the resource will be
371
stored;
372
calWS:before-min-date-time: The resource submitted in the PUT request, or targeted by a COPY
373
or MOVE request, MUST have all of its iCalendar DATE or DATE-TIME property values (for each
374
recurring instance) greater than or equal to the value of the CalDAV:min- date-time property value
375
on the calendar collection where the resource will be stored;
376
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 17 of 37
calWS:after-max-date-time: The resource submitted in the PUT request, or targeted by a COPY or
377
MOVE request, MUST have all of its iCalendar DATE or DATE-TIME property values (for each
378
recurring instance) less than the value of the CalDAV:max-date-time property value on the calendar
379
collection where the resource will be stored;
380
calWS:too-many-instances: The resource submitted in the PUT request, or targeted by a COPY
381
or MOVE request, MUST generate a number of recurring instances less than or equal to the value
382
of the CalDAV: max-instances property value on the calendar collection where the resource will be
383
stored;
384
calWS:too-many-attendees-per-instance: The resource submitted in the PUT request, or targeted
385
by a COPY or MOVE request, MUST have a number of ATTENDEE properties on any one instance
386
less than or equal to the value of the CalDAV:max-attendees-per-instance property value on the
387
calendar collection where the resource will be stored;
388
5.4 Example - successful POST:
389
>>Request
390
391
POST /user/fred/calendar/?action=create HTTP/1.1
392
Host: example.com
393
Content-Type: application/xml+calendar; charset="utf-8"
394
Content-Length: ?
395
396
<?xml version="1.0" encoding="utf-8" ?>
397
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
398
<vcalendar>
399
...
400
</vcalendar>
401
</icalendar>
402
403
>>Response
404
405
HTTP/1.1 201 Created
406
Location: http://example.com/user/fred/calendar/event1.ics
407
5.5 Example - unsuccessful POST:
408
>>Request
409
410
POST /user/fred/readcalendar/?action=create HTTP/1.1
411
Host: example.com
412
Content-Type: text/text; charset="utf-8"
413
Content-Length: ?
414
415
This is not an xml calendar object
416
417
>>Response
418
419
HTTP/1.1 403 Forbidden
420
<?xml version="1.0" encoding="utf-8"
421
xmlns:D="DAV:"
422
xmlns:C="urn:ietf:params:xml:ns:caldav" ?>
423
<D:error>
424
<C:supported-calendar-data/>
425
<D:description>Not an icalendar object</D:description>
426
</D:error>
427
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 18 of 37
6 Retrieving resources
428
A simple GET on the href will return a named resource. If that resource is a recurring event or task with
429
overrides, the entire set will be returned. The desired format is specified in the ACCEPT header. The
430
default form is application/xml+calendar
431
6.1 Request parameters
432
none
433
6.2 Responses:
434
200: OK
435
403: Forbidden - no access
436
406 The requested format specified in the accept header is not supported.
437
6.3 Example - successful fetch:
438
>>Request
439
440
GET /user/fred/calendar/event1.ics HTTP/1.1
441
Host: example.com
442
443
>>Response
444
445
HTTP/1.1 200 OK
446
Content-Type: application/xml+calendar; charset="utf-8"
447
Content-Length: ?
448
449
<?xml version="1.0" encoding="utf-8" ?>
450
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
451
<vcalendar>
452
...
453
</vcalendar>
454
</icalendar>
455
6.4 Example - unsuccessful fetch:
456
>>Request
457
458
PUT /user/fred/calendar/noevent1.ics HTTP/1.1
459
Host: example.com
460
461
>>Response
462
463
HTTP/1.1 404 Not found
464
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 19 of 37
7 Updating resources
465
Resources are updated with the PUT method targeted at the resource href. The body of the request
466
contains a complete new resource which effectively replaces the targeted resource. To allow for optimistic
467
locking of the resource use the if-match header.
468
When updating a recurring event all overrides and master must be supplied as part of the content.
469
Preconditions as specified in Section 5.3 are applicable.
470
7.1 Responses:
471
200: OK
472
304: Not modified - entity was modified by some other request
473
403: Forbidden - no access, does not exist etc. See error response
474
475
Example 7-1: Successful Update
476
>>Request
477
478
PUT /user/fred/calendar/event1.ics HTTP/1.1
479
Host: example.com
480
Content-Type: application/xml+calendar; charset="utf-8"
481
Content-Length: ?
482
483
<?xml version="1.0" encoding="utf-8" ?>
484
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
485
<vcalendar>
486
...
487
</vcalendar>
488
</icalendar>
489
490
>>Response
491
492
HTTP/1.1 200 OK
493
Example 7-2: Unsuccessful Update
494
>>Request
495
496
PUT /user/fred/readcalendar/event1.ics HTTP/1.1
497
Host: example.com
498
Content-Type: application/xml+calendar; charset="utf-8"
499
Content-Length: ?
500
501
<?xml version="1.0" encoding="utf-8" ?>
502
<icalendar xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
503
<vcalendar>
504
...
505
</vcalendar>
506
</icalendar>
507
508
>>Response
509
510
HTTP/1.1 403 Forbidden
511
Content-Type: application/xml; charset="utf-8"
512
Content-Length: xxxx
513
514
<?xml version="1.0" encoding="utf-8"
515
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 20 of 37
xmlns:D="DAV:"
516
xmlns:CW=" http://docs.oasis-open.org/ws-calendar/ns/REST/" ?>
517
<CW:error>
518
<CW:target-exists/>
519
<CW:description>Target of update must exist</C:description>
520
</CW:error>
521
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 21 of 37
8 Deletion of resources
522
Delete is defined in [RFC 2616] Section 9.7. In addition to conditions defined in that specification, servers
523
must remove any references from the deleted resource to other resources. Resources are deleted with
524
the DELETE method targeted at the resource URL. After a successful completion of a deletion a GET on
525
that URL must result in a 404 - Not Found status.
526
8.1 Delete for Collections
527
Delete for collections may or may not be supported by the server. Certain collections are considered
528
undeletable. On a successful deletion of a collection all contained resources to any depth must also be
529
deleted.
530
8.2 Responses:
531
200: OK
532
403: Forbidden - no access
533
404: Not Found
534
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 22 of 37
9 Querying calendar resources
535
Querying provides a mechanism by which information can be obtained from the service through possibly
536
complex queries. A list of icalendar properties can be specified to limit the amount of information returned
537
to the client. A query takes the parts
538
Limitations on the data returned
539
Selection of the data
540
Optional timezone id for floating time calculations.
541
The current specification uses CalDAV multiget and calendar-query XML bodies as specified in [RFC
542
4791] with certain limitations and differences.
543
1. The POST method is used for all requests, the action being identified by the outer element.
544
2. While CalDAV servers generally only support [RFC 5545] and assume that as the default, the
545
delivery format for CalWS will, by default, be [draft-xcal].
546
3. The CalDAV query allows the specification of a number of DAV properties. Specification of these
547
properties, with the exception of DAV:getetag, is considered an error in CalWS.
548
4. The CalDAV:propnames element is invalid
549
With those differences, the CalDAV specification is the normative reference for this operation.
550
9.1 Limiting data returned
551
This is achieved by specifying one of the following
552
CalDAV:allprop return all properties (some properties are specified as not being part of the allprop
553
set so are not returned)
554
CalDAV:prop An element which contains a list of properties to be returned . May only contain
555
DAV:getetag and CalDAV:calendar-data
556
Of particular interest, and complexity, is the calendar-data property which can contain a time range to limit
557
the range of recurrences returned and/or a list of calendar properties to return.
558
9.2 Pre/postconditions for calendar queries
559
The preconditions as defined in in [RFC 4791] Section 7.8 apply here. CalDav errors may be reported by
560
the service when preconditions or postconditions are violated.
561
9.3 Example: time range limited retrieval
562
This example shows the time-range limited retrieval from a calendar which results in 2 events, one a
563
recurring event and one a simple non-recurring event.
564
>> Request <<
565
566
POST /user/fred/calendar/ HTTP/1.1
567
Host: calWS.example.com
568
Depth: 1
569
Content-Type: application/xml; charset="utf-8"
570
Content-Length: xxxx
571
572
<?xml version="1.0" encoding="utf-8" ?>
573
<C:calendar-query xmlns:D="DAV:"
574
xmlns:C="urn:ietf:params:xml:ns:caldav">
575
<D:prop>
576
<D:getetag/>
577
<C:calendar-data content-type="application/xml+calendar" >
578
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 23 of 37
<C:comp name="VCALENDAR">
579
<C:prop name="VERSION"/>
580
<C:comp name="VEVENT">
581
<C:prop name="SUMMARY"/>
582
<C:prop name="UID"/>
583
<C:prop name="DTSTART"/>
584
<C:prop name="DTEND"/>
585
<C:prop name="DURATION"/>
586
<C:prop name="RRULE"/>
587
<C:prop name="RDATE"/>
588
<C:prop name="EXRULE"/>
589
<C:prop name="EXDATE"/>
590
<C:prop name="RECURRENCE-ID"/>
591
</C:comp>
592
</C:comp>
593
</C:calendar-data>
594
</D:prop>
595
<C:filter>
596
<C:comp-filter name="VCALENDAR">
597
<C:comp-filter name="VEVENT">
598
<C:time-range start="20060104T000000Z"
599
end="20060105T000000Z"/>
600
</C:comp-filter>
601
</C:comp-filter>
602
</C:filter>
603
</C:calendar-query>
604
605
>> Response <<
606
607
HTTP/1.1 207 Multi-Status
608
Date: Sat, 11 Nov 2006 09:32:12 GMT
609
Content-Type: application/xml; charset="utf-8"
610
Content-Length: xxxx
611
612
<?xml version="1.0" encoding="utf-8" ?>
613
<D:multistatus xmlns:D="DAV:"
614
xmlns:C="urn:ietf:params:xml:ns:caldav">
615
<D:response>
616
<D:href>http://cal.example.com/bernard/work/abcd2.ics</D:href>
617
<D:propstat>
618
<D:prop>
619
<D:getetag>"fffff-abcd2"</D:getetag>
620
<C:calendar-data content-type="application/xml+calendar" >
621
<xc:icalendar
622
xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
623
<xc:vcalendar>
624
<xc:properties>
625
<xc:calscale><text>GREGORIAN</text></xc:calscale>
626
<xc:prodid>
627
<xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
628
</xc:prodid>
629
<xc:version><xc:text>2.0</xc:text></xc:version>
630
</xc:properties>
631
<xc:components>
632
<xc:vevent>
633
<xc:properties>
634
<xc:dtstart>
635
<xc:parameters>
636
<xc:tzid>US/Eastern<xc:tzid>
637
<xc:parameters>
638
<xc:date-time>20060102T120000</xc:date-time>
639
</xc:dtstart>
640
<xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
641
<xc:summary>
642
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 24 of 37
<xc:text>Event #2</xc:text>
643
</xc:summary>
644
<xc:uid>
645
<xc:text>[email protected]</xc:text>
646
</xc:uid>
647
<xc:rrule>
648
<xc:recur>
649
<xc:freq>DAILY</xc:freq>
650
<xc:count>5</xc:count>
651
</xc:recur>
652
</xc:rrule>
653
</xc:properties>
654
</xc:vevent>
655
656
<xc:vevent>
657
<xc:properties>
658
<xc:dtstart>
659
<xc:parameters>
660
<xc:tzid>US/Eastern<xc:tzid>
661
<xc:parameters>
662
<xc:date-time>20060104T140000</xc:date-time>
663
</xc:dtstart>
664
<xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
665
<xc:summary>
666
<xc:text>Event #2 bis</xc:text>
667
</xc:summary>
668
<xc:uid>
669
<xc:text>[email protected]</xc:text>
670
</xc:uid>
671
<xc:recurrence-id>
672
<xc:parameters>
673
<xc:tzid>US/Eastern<xc:tzid>
674
<xc:parameters>
675
<xc:date-time>20060104T120000</xc:date-time>
676
</xc:recurrence-id>
677
<xc:rrule>
678
<xc:recur>
679
<xc:freq>DAILY</xc:freq>
680
<xc:count>5</xc:count>
681
</xc:recur>
682
</xc:rrule>
683
</xc:properties>
684
</xc:vevent>
685
686
<xc:vevent>
687
<xc:properties>
688
<xc:dtstart>
689
<xc:parameters>
690
<xc:tzid>US/Eastern<xc:tzid>
691
<xc:parameters>
692
<xc:date-time>20060106T140000</xc:date-time>
693
</xc:dtstart>
694
<xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
695
<xc:summary>
696
<xc:text>Event #2 bis bis</xc:text>
697
</xc:summary>
698
<xc:uid>
699
<xc:text>[email protected]</xc:text>
700
</xc:uid>
701
<xc:recurrence-id>
702
<xc:parameters>
703
<xc:tzid>US/Eastern<xc:tzid>
704
<xc:parameters>
705
<xc:date-time>20060106T120000</xc:date-time>
706
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 25 of 37
</xc:recurrence-id>
707
<xc:rrule>
708
<xc:recur>
709
<xc:freq>DAILY</xc:freq>
710
<xc:count>5</xc:count>
711
</xc:recur>
712
</xc:rrule>
713
</xc:properties>
714
</xc:vevent>
715
</xc:components>
716
</xc:vcalendar>
717
</xc:icalendar>
718
</C:calendar-data>
719
</D:prop>
720
<D:status>HTTP/1.1 200 OK</D:status>
721
</D:propstat>
722
</D:response>
723
<D:response>
724
<D:href>http://cal.example.com/bernard/work/abcd3.ics</D:href>
725
<D:propstat>
726
<D:prop>
727
<D:getetag>"fffff-abcd3"</D:getetag>
728
<C:calendar-data content-type="application/xml+calendar" >
729
<xcal:icalendar
730
xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
731
<xc:vcalendar>
732
<xc:properties>
733
<xc:calscale><text>GREGORIAN</text></xc:calscale>
734
<xc:prodid>
735
<xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
736
</xc:prodid>
737
<xc:version><xc:text>2.0</xc:text></xc:version>
738
</xc:properties>
739
<xc:components>
740
<xc:vevent>
741
<xc:properties>
742
<xc:dtstart>
743
<xc:parameters>
744
<xc:tzid>US/Eastern<xc:tzid>
745
<xc:parameters>
746
<xc:date-time>20060104T100000</xc:date-time>
747
</xc:dtstart>
748
<xc:duration><xc:duration>PT1H</xc:duration></xc:duration>
749
<xc:summary>
750
<xc:text>Event #3</xc:text>
751
</xc:summary>
752
<xc:uid>
753
<xc:text>[email protected]</xc:text>
754
</xc:uid>
755
<xc:rrule>
756
<xc:recur>
757
<xc:freq>DAILY</xc:freq>
758
<xc:count>5</xc:count>
759
</xc:recur>
760
</xc:rrule>
761
</xc:properties>
762
</xc:vevent>
763
</xc:components>
764
</xc:vcalendar>
765
</xc:icalendar>
766
</C:calendar-data>
767
</D:prop>
768
<D:status>HTTP/1.1 200 OK</D:status>
769
</D:propstat>
770
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 26 of 37
</D:response>
771
</D:multistatus>
772
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 27 of 37
10 Free-busy queries
773
Free-busy queries are used to obtain free-busy information for a calendar-collection or principals. The
774
result contains information only for events to which the current principal has sufficient access.
775
When targeted at a calendar collection the result is based only on the calendaring entities contained in
776
that collection. When targeted at a principal free-busy URL the result will be based on all information
777
which affect the principals free-busy status, for example availability.
778
The possible targets are:
779
A calendar collection URL
780
The XRD link with relation CalWS/current-principal-freebusy
781
The XRD link with relation CalWS/principal-freebusy with a principal given in the request.
782
The query follows the specification defined in [FreeBusy Read URL] with certain limitations. As an
783
authenticated user to the CalWS service scheduling read-freebusy privileges must have been granted. As
784
an unauthenticated user equivalent access must have been granted to unauthenticated access.
785
Freebusy information is returned by default as xcalendar vfreebusy components, as defined by [draft-
786
xcal]. Such a component is not meant to conform to the requirements of VFREEBUSY components in
787
[RFC 5546]. The VFREEBUSY component SHOULD conform to section "4.6.4 Free/Busy Component" of
788
[RFC 5545]. A client SHOULD ignore the ORGANIZER field..
789
Since a Freebusy query can only refer to a single user, a client will already know how to match the result
790
component to a user. A server MUST only return a single vfreebusy component.
791
10.1 ACCEPT header
792
The Accept header is used to specify the format for the returned data. In the absence of a header the
793
data should be returned as specified in [draft-xcal], that is, as if the following had been specified
794
ACCEPT: application/xml+calendar
795
10.2 URL Query Parameters
796
None of these parameters are required except for the conditions noted below. Appropriate defaults will be
797
supplied by the server.
798
10.2.1 start
799
Default: The default value is left up to the server. It may be the current day, start of the current
800
month, etc.
801
Description:Specifies the start date for the Freebusy data. The server is free to ignore this value and
802
return data in any time range. The client must check the data for the returned time range.
803
Format:A profile of an [RFC3339] Date/Time. Fractional time is not supported. The server MUST
804
support the expanded version e.g.
805
2007-01-02T13:00:00-08:00
806
It is up to the server to interpret local date/times.
807
Example:
808
2007-02-03T15:30:00-0800
809
2007-12-01T10:15:00Z
810
Notes: Specifying only a start date/time without specifying an end-date/time or period should be
811
interpreted as in [RFC 5545]. The effective period should cover the remainder of that day.
812
Date-only values are disallowed as the server cannot determine the correct start of the day. Only
813
UTC or date/time with offset values are permitted.
814
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 28 of 37
10.2.2 end
815
Default: Same as start
816
Description: Specifies the end date for the Freebusy data. The server is free to ignore this value.
817
Format: Same as start
818
Example: Same as start
819
10.2.3 period
820
Default: The default value is left up to the server. The recommended value is "P42D".
821
Description: Specifies the amount of Freebusy data to return. A client cannot specify both a period
822
and an end date. Period is relative to the start parameter.
823
Format: A duration as defined in section 4.3.6 of [RFC 5545]
824
Example:
825
P42D
826
10.2.4 account
827
Default: none
828
Description: Specifies the principal when the request is targeted at the XRD CalWS/principal-
829
freebusy. Specification of this parameter is an error otherwise.
830
Format: Server specific
831
Example:
832
fred
833
/principals/users/jim
834
[email protected]
835
10.3 URL parameters - notes
836
The server is free to ignore the start, end and period parameters. It is recommended that the server return
837
at least 6 weeks of data from the current day.
838
A client MUST check the time range in the VFREEBUSY response as a server may return a different time
839
range than the requested range.
840
10.4 HTTP Operations
841
The server SHOULD return an Etag response header for a successful GET request targeting a Freebusy
842
read URL. Clients MAY use the Etag response header value to do subsequent "conditional" GET
843
requests that will avoid re-sending the Freebusy data again if it has not changed.
844
10.5 Response Codes
845
Below are the typical status codes returned by a GET request targeting a Free-busy URL. Note that other
846
HTTP status codes not listed here might also be returned by a server.
847
200 OK
848
302 Found
849
400 Start parameter could not be understood / End parameter could not be understood / Period
850
parameter could not be understood
851
401 Unauthorized
852
403 Forbidden
853
404 The data for the requested principal is not currently available, but may be available later.
854
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 29 of 37
406 The requested format in the accept header is not supported.
855
410 The data for the requested principal is no longer available
856
500 General server error
857
10.6 Examples
858
The following are examples of URLs used to retrieve Free-busy data for a user:
859
http://www.example.com/freebusy/[email protected]?
860
start=2007-09-01T00:00:00-08:00&end=2007-09-31T00:00:00-08:00
861
862
http://www.example.com/freebusy/[email protected]?
863
start=2007-09-01T00:00:00-08:00&end=2007-09-31T00:00:00-08:00
864
865
http://www.example.com/freebusy/[email protected]
866
867
http://www.example.com/freebusy?user=user%[email protected]&
868
start=2008-01-01T00:00:00Z&end=2008-12-31T00:00:00Z
869
Some Request/Response Examples:
870
A URL with no query parameters:
871
>> Request <<
872
GET /freebusy/bernard/ HTTP/1.1
873
Host: www.example.com
874
875
>> Response <<
876
HTTP/1.1 200 OK
877
Content-Type: application/xml+calendar; charset="utf-8"
878
Content-Length: xxxx
879
880
<xc:icalendar xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
881
<xc:vcalendar>
882
<xc:properties>
883
<xc:calscale><text>GREGORIAN</text></xc:calscale>
884
<xc:prodid>
885
<xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
886
</xc:prodid>
887
<xc:version><xc:text>2.0</xc:text></xc:version>
888
</xc:properties>
889
<xc:components>
890
<xc:vfreebusy>
891
<xc:properties>
892
<xc:uid>
893
<xc:text>[email protected]</xc:text>
894
</xc:uid>
895
<xc:dtstart>
896
<xc:date-time>20060101T000000Z</xc:date-time>
897
</xc:dtstart>
898
<xc:dtend>
899
<xc:date-time>20060108T000000Z</xc:date-time>
900
</xc:dtend>
901
<xc:dtstamp>
902
<xc:date-time>20050530T123421Z</xc:date-time>
903
</xc:dtstamp>
904
<xc:freebusy>
905
<xc:parameters>
906
<xc:fbtype>BUSYTENTATIVE<xc:fbtype>
907
<xc:parameters>
908
<xc:period>20060102T100000Z/20060102T120000Z</xc:period>
909
</xc:freebusy>
910
<xc:freebusy>
911
<xc:period>20060103T100000Z/20060103T120000Z</xc:period>
912
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 30 of 37
</xc:freebusy>
913
<xc:freebusy>
914
<xc:period>20060104T100000Z/20060104T120000Z</xc:period>
915
</xc:freebusy>
916
<xc:freebusy>
917
<xc:parameters>
918
<xc:fbtype>BUSYUNAVAILABLE<xc:fbtype>
919
<xc:parameters>
920
<xc:period>20060105T100000Z/20060105T120000Z</xc:period>
921
</xc:freebusy>
922
<xc:freebusy>
923
<xc:period>20060106T100000Z/20060106T120000Z</xc:period>
924
</xc:freebusy>
925
</xc:vfreebusy>
926
</xc:components>
927
</xc:vcalendar>
928
<xc:icalendar>
929
A URL with start and end parameters:
930
>> Request <<
931
GET /freebusy/[email protected]?start=2007-09-01T00:00:00-08:00&end=2007-09-
932
31T00:00:00-08:00
933
HTTP/1.1
934
Host: www.example.com
935
936
>> Response <<
937
HTTP/1.1 200 OK
938
Content-Type: application/xml+calendar; charset="utf-8"
939
Content-Length: xxxx
940
941
<xc:icalendar xmlns:xc="urn:ietf:params:xml:ns:icalendar-2.0">
942
<xc:vcalendar>
943
<xc:properties>
944
<xc:calscale><text>GREGORIAN</text></xc:calscale>
945
<xc:prodid>
946
<xc:text>-//Example Inc.//Example Calendar//EN</xc:text>
947
</xc:prodid>
948
<xc:version><xc:text>2.0</xc:text></xc:version>
949
</xc:properties>
950
<xc:components>
951
<xc:vfreebusy>
952
<xc:properties>
953
<xc:uid>
954
<xc:text>[email protected]</xc:text>
955
</xc:uid>
956
<xc:dtstart>
957
<xc:date-time>20070901T000000Z</xc:date-time>
958
</xc:dtstart>
959
<xc:dtend>
960
<xc:date-time>20070931T000000Z</xc:date-time>
961
</xc:dtend>
962
<xc:dtstamp>
963
<xc:date-time>20050530T123421Z</xc:date-time>
964
</xc:dtstamp>
965
<xc:freebusy>
966
<xc:period>20070915T230000Z/20070916T010000Z</xc:period>
967
</xc:freebusy>
968
</xc:vfreebusy>
969
</xc:components>
970
</xc:vcalendar>
971
<xc:icalendar>
972
A URL for which the server does not have any data for that user:
973
>> Request <<
974
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 31 of 37
GET /freebusy/[email protected]?start=2012-12-01T00:00:00-08:00&end=2012-12-
975
31T00:00:00-08:00
976
HTTP/1.1
977
Host: www.example.com
978
979
>> Response <<
980
HTTP/1.1 404 No data
981
982
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 32 of 37
11 Conformance
983
The last numbered section in the specification must be the Conformance section. Conformance
984
Statements/Clauses go here.
985
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 33 of 37
Appendix A. Acknowledgments
986
The following individuals have participated in the creation of this specification and are gratefully
987
acknowledged:
988
Participants:
989
Bruce Bartell, Southern California Edison
990
Brad Benson, Trane
991
Edward Cazalet, Individual
992
Toby Considine, University of North Carolina at Chapel Hill
993
William Cox, Individual
994
Sharon Dinges, Trane
995
Mike, Douglass, Rensselaer Polytechnic Institute
996
Craig Gemmill, Tridium, Inc.
997
Girish Ghatikar, Lawrence Berkeley National Laboratory
998
Gerald Gray, Southern California Edison
999
David Hardin, ENERNOC
1000
Gale Horst, Electric Power Research Institute (EPRI)
1001
Gershon Janssen, Individual
1002
Ed Koch, Akuacom Inc.
1003
Benoit Lepeuple, LonMark International*
1004
Carl Mattocks, CheckMi*
1005
Robert Old, Siemens AG
1006
Alexander Papaspyrou, Technische Universitat Dortmund
1007
Joshua Phillips, ISO/RTO Council (IRC)
1008
Jeremy J. Roberts, LonMark International
1009
David Thewlis, CalConnect
1010
1011
The Calendaring and Scheduling Consortium (CalConnect) TC-XML committee worked closely with WS-
1012
Calendar Technical Committee, bridging to developing IETF standards and contributing the services
1013
definitions that make up Services in Section 4. The Technical Committee gratefully acknowledges their
1014
assistance and cooperation as well. Contributors to TC XML include:
1015
Cyrus Daboo, Apple
1016
Mike Douglass, Rensselaer Polytechnic Institute
1017
Steven Lees, Microsoft
1018
Tong Li, IBM
1019
1020
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 34 of 37
Appendix B. An Introduction to Internet Calendaring
1021
The WS-Calendar Technical Committee thanks CalConnect for contributing this overview of iCalendar
1022
and its use.
1023
B.1 icalendar
1024
B.1.1 History
1025
The iCalendar specification was first produced by the IETF in 1998 as RFC 2445 [1]. Since then it has
1026
become the dominant standard for calendar data interchange on the internet and between devices
1027
(desktop computers, mobile phones etc.). The specification was revised in 2009 as RFC 5545 [4].
1028
Alongside iCalendar is the iTIP specification (RFC 2446 [2] and revised as RFC 5546[5]) that defines how
1029
iCalendar is used to carry out scheduling operations (for example, how an organizer can invite attendees
1030
to a meeting and receive their replies). This forms the basis for email-based scheduling using iMIP (the
1031
specification that describes how to use iTIP with email - RFC 6047 [3]).
1032
iCalendar itself is a text-based data format. However, an XML format is also available, providing a one-to-
1033
one mapping to the text format (draft [7]).
1034
iCalendar data files typically have a .ics file name extension. Most desktop calendar clients can import or
1035
export iCalendar data, or directly access such data over the Internet using a variety of protocols.
1036
B.1.2 Data model
1037
The iCalendar data format has a well defined data model. "iCalendar objects" encompass a set of
1038
"iCalendar Components" each of which contains a set of "iCalendar properties" and possibly other sub-
1039
Components. An iCalendar property consists of a name, a set of optional parameters (specified as "key-
1040
value" pairs) and a value.
1041
iCalendar Components include:
1042
"VEVENT" which represents an event
1043
"VTODO" which represents a task or to-do
1044
"VJOURNAL" which represents a journal entry
1045
"VFREEBUSY" which represents periods of free or busy time information
1046
"VTIMEZONE" which represents a timezone definition (timezone offset and daylight saving rules)
1047
"VALARM" is currently the only defined sub-Component and is used to set alarms or reminders on events
1048
or tasks.
1049
Properties include:
1050
"DTSTART" which represents a start time for a Component
1051
"DTEND" which represents an end time for a Component
1052
"SUMMARY" which represents a title or summary for a Component
1053
"RRULE" which can specify rules for repeating events or tasks (for example, every day, every week on
1054
Tuesdays, etc.)
1055
"ORGANIZER" which represents the calendar user who is organizing an event or assigning a task
1056
"ATTENDEE" which represents calendar users attending an event or assigned a task
1057
In addition to this data model and the pre-defined properties, the specification defines how all those are
1058
used together to define the semantics of calendar objects and scheduling. The semantics are basically a
1059
set of rules stating how all the Components and properties are used together to ensure that all iCalendar
1060
products can work together to achieve good interoperability. For example, a rule requires that all events
1061
must have one and only one "DTSTART" property. The most important part of the iCalendar specification
1062
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 35 of 37
is the semantics of the calendaring model that it represents. The use of text or XML to encode those is
1063
secondary.
1064
B.1.3 Scheduling
1065
The iTIP specification defines how iCalendar objects are exchanged in order to accomplish the key task
1066
needed to schedule events or tasks. An example of a simple workflow is as follows:
1067
1.
To schedule an event, an organizer creates the iCalendar object representing the event and adds
1068
calendar users as attendees.
1069
2.
The organizer then sends an iTIP "REQUEST" message to all the attendees.
1070
3.
Upon receipt of the scheduling message, each attendee can decide whether they want to attend
1071
the meeting or not.
1072
4.
Each attendee can then respond back to the organizer using an iTIP "REPLY" message
1073
indicating their own attendance status.
1074
iTIP supports other types of scheduling messages, for example, to cancel meetings, add new instances to
1075
a repeating meeting, etc.
1076
B.1.4 Extensibility
1077
iCalendar was designed to be extensible, allowing for new Components, properties and parameters to be
1078
defined as needed. A registry exists to maintain the list of standard extensions with references to their
1079
definitions to ensure anyone can use them and work well with others.
1080
B.2 Calendar data access and exchange protocols
1081
B.2.1 Internet Calendar Subscriptions
1082
An Internet calendar subscription is simply an iCalendar data file made available on a web server. Users
1083
can use this data in two ways:
1084
– The data can be downloaded from the web server and then imported directly into an iCalendar
1085
aware client. This solution works well for calendar data that is not likely to change over time (for
1086
example the list of national holidays for the next year).
1087
– Calendar clients that support "direct" subscriptions can use the URL to the calendar data on the
1088
web server to download the calendar data themselves. Additionally, the clients can check the web
1089
server on a regular basis for updates to the calendar data, and then update their own cached
1090
copy of it. This allows calendar data that changes over time to be kept synchronized.
1091
B.2.2 CalDAV
1092
CalDAV is a calendar access protocol and is defined in RFC 4791 [6]. The protocol is based on WebDAV
1093
which is an extension to HTTP that provides enhanced capabilities for document management on web
1094
servers.
1095
CalDAV is used in a variety of different environments, ranging from very large internet service providers,
1096
to large and small corporations or institutions, and to small businesses and individuals.
1097
CalDAV clients include desktop applications, mobile devices and browser-based solutions. It can also be
1098
used by "applets", for example, a web page panel that displays a user's upcoming events.
1099
One of the key aspects of CalDAV is its data model. Simply put, it defines a "calendar home" for each
1100
calendar user, within which any number of "calendars" can be created. Each "calendar" can contain any
1101
number of iCalendar objects representing individual events, tasks or journal entries. This data model
1102
ensures that clients and servers can interoperate well.
1103
In addition to providing simple operations to read, write and delete calendar data, CalDAV provides a
1104
querying mechanism to allow clients to fetch calendar data matching specific criteria. This is commonly
1105
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 36 of 37
used by clients to do "time-range" queries, i.e., find the set of events that occur within a given start/end
1106
time period.
1107
CalDAV also supports access control allowing for features such as delegated calendars and calendar
1108
sharing.
1109
CalDAV also specifies how scheduling operations can be done using the protocol. Whilst it uses the
1110
semantics of the iTIP protocol, it simplifies the process by allowing simple calendar data write operations
1111
to trigger the sending of scheduling messages, and it has the server automatically process the receipt of
1112
scheduling messages. Scheduling can be done with other users on the CalDAV server or with calendar
1113
users on other systems (via some form of "gateway").
1114
B.2.3 ActiveSync/SyncML
1115
ActiveSync and SyncML are technologies that allow multiple devices to synchronize data with a server,
1116
with calendar data being one of the classes of data supported. These have typically been used for low-
1117
end and high-end mobile devices.
1118
B.2.4 CalWS
1119
CalWS refers to a set of web services calendar access APIs developed under a cooperative agreement
1120
between The Calendaring and Scheduling Consortium (CalConnect) and OASIS, and being published as
1121
a work product of the WS-Calendar Technical Committee. CalWS defines an API to access and
1122
manipulate calendar data stored on a server. It follows a similar data model to CalDAV and has been
1123
designed to co-exist with a CalDAV service offering the same data.
1124
This specification is part of the CalWS set.
1125
B.2.5 iSchedule
1126
iSchedule is a protocol to allow scheduling between users on different calendaring systems and across
1127
different internet domains. It transports iTIP scheduling messages using HTTP between servers. Servers
1128
use DNS and various security mechanisms to determine the authenticity of messages received.
1129
It has been specifically designed to be independent of any calendar system in use at the endpoints, so
1130
that it is compatible with many different systems. This allows organizations with different calendar
1131
systems to exchange scheduling messages with each other, and also allows a single organization with
1132
multiple calendar systems (for example due to mergers, or different departmental requirements) to
1133
exchange scheduling messages between users of each system.
1134
B.3 References
1135
[1] https://datatracker.ietf.org/doc/rfc2445/ : ‘Internet Calendaring and Scheduling Core Object
1136
Specification’
1137
[2] https://datatracker.ietf.org/doc/rfc2446/ :‘iCalendar Transport-Independent Interoperability Protocol’
1138
[3] https://datatracker.ietf.org/doc/rfc6047/ : ‘iCalendar Message-Based Interoperability Protocol’
1139
[4] https://datatracker.ietf.org/doc/rfc5545/ :‘Internet Calendaring and Scheduling Core Object
1140
Specification’
1141
[5] https://datatracker.ietf.org/doc/rfc5546/ : ‘iCalendar Transport-Independent Interoperability Protocol’
1142
[6] https://datatracker.ietf.org/doc/rfc4791/ : ‘Calendaring Extensions to WebDAV’
1143
[7] https://datatracker.ietf.org/doc/draft-daboo-et-al-icalendar-in-xml/ : ‘xCal: The XML format for
1144
iCalendar’
1145
1146
1147
ws-calendar-rest-v1.0-wd05 Working Draft 05 17 February 2012
Copyright (c) 2012 The Calendaring and Scheduling Consortium. All Rights Reserved. Page 37 of 37
Appendix C. Revision History
1148
Revision
Editor
Changes Made
ws-calendar-wd19
Toby Considine
Originally contributed by Mike Douglass as part
of WS-Calendar v1.0 Specification. See full
history in that document.
WD02
Toby Considine
Ported to separate document. “Promoted” all
section headers.
WD03
Toby Considine
Added Intro, updated namespaces to meet
OASIS standard
WD04
Toby Considine
Additional namespace clean-up in response to
Cover comments.
Consisten capitalization of calWS when used as
a namespace identifier
Clean-up of CalWS discussion in appendix
WD05
Toby Considine
Types, capitalization, missing XRD reference
1149
1150