Table of contents
Introduction
The OpenPaaS calendar API uses jCal specification as defined in the jCal RFC which defines a JSON format for iCalendar.
Prerequisites
- The following samples assumes that you followed the steps to get the cookies used to authenticate user as defined in Authentication documentation
- In several places in the following REST API samples, parameters will be defined by using
{mustache}. Developers will have to replace values by valid ones - Standard errors are not listed which does not means that they will not occur (HTTP 4XX and 5XX ones)
CRUD operations
Get available calendars
Request
GET https://HOST:PORT/dav/api/calendars/{userId}.json
Headers
accept: application/calendar+json
Response
The response is formatted using Hypertext application Language. Calendar list is available in the _embedded element as dav:calendar array. The href value is the calendar URL which can be used to do operations on the calendar.
As of 170503 and reported in CAL-670, the href links are not well formatted.
Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
"_links":{
"self":{
"href":"/sdav/calendars/57fca675a91c8d01a36ac26b.json"
}
},
"_embedded":{
"dav:calendar":[
{
"_links":{
"self":{
"href":"/sdav/calendars/57fca675a91c8d01a36ac26b/events.json"
}
},
"calendarserver:ctag":"http://sabre.io/ns/sync/101"
},
{
"_links":{
"self":{
"href":"/sdav/calendars/57fca675a91c8d01a36ac26b/aee302d8-12dc-4c8d-94cf-991da9b453ab.json"
}
},
"dav:name":"My public calendar",
"caldav:description":"",
"calendarserver:ctag":"http://sabre.io/ns/sync/7",
"apple:color":"#f7e511"
}
]
}
}
Create a calendar
Request
The {userId} is the id of the authenticated user.
POST https://HOST:PORT/dav/api/calendars/{userId}.json
Body
1
2
3
4
5
6
{
"id": "ebdfe2b9-694a-4dc3-98fa-0f7acbfdc739",
"dav:name": "My calendar name",
"apple:color": "#68c289",
"caldav:description": "The calendar description"
}
List events in calendar
Request
REPORT https://openpaas.linagora.com/dav/api/calendars/57fca675a91c8d01a36ac26b/events.json'
Body
1
2
3
4
5
6
{
"match": {
"start": "20170430T000000",
"end": "20170613T000000"
}
}'
Create an event in a calendar
In order to create an event, the user must send the new event as jCal in an existing calendar (the list of calendars and their URL can be found as described above).
Request
The {eventId} is defined by the developer. We suggest to use an uuid generator to have unique ids.
PUT https://HOST:PORT/dav/api/calendars/{userId}/{calendarId}/{eventId}.ics
Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
[
"vcalendar",
[],
[
[
"vevent",
[
[
"uid",
{},
"text",
"0d52de98-127c-4625-8583-57ec07e9bfd9"
],
[
"transp",
{},
"text",
"OPAQUE"
],
[
"dtstart",
{
"tzid":"Europe/Berlin"
},
"date-time",
"2017-05-03T16:00:00"
],
[
"dtend",
{
"tzid":"Europe/Berlin"
},
"date-time",
"2017-05-03T17:00:00"
],
[
"organizer",
{
"cn":"Christophe HAMERLING"
},
"cal-address",
"mailto:chamerling@linagora.com"
],
[
"class",
{},
"text",
"PUBLIC"
],
[
"summary",
{},
"text",
"Barcamp doc test"
],
[
"location",
{},
"text",
"Paris"
],
[
"description",
{},
"text",
"Blahblah"
],
[
"attendee",
{
"partstat":"NEEDS-ACTION",
"rsvp":"TRUE",
"role":"REQ-PARTICIPANT",
"cn":"Michael BAILLY"
},
"cal-address",
"mailto:mbailly@linagora.com"
],
[
"attendee",
{
"partstat":"ACCEPTED",
"rsvp":"FALSE",
"role":"CHAIR"
},
"cal-address",
"mailto:chamerling@linagora.com"
]
]
]
]
]
Response
{"id":"491cd007-3646-4fe2-93a5-7a8281e9e36d"}
Delete an event
Request
DELETE https://HOST:PORT/dav/api/calendars/{userId}/{calendarId}/{eventId}.ics
Response
Body
{"id":"491cd007-3646-4fe2-93a5-7a8281e9e36d"}