holm/egroupware
1
1
Fork 0
forked from extern/egroupware
Code Issues Pull Requests Packages Projects Releases Wiki Activity
82c8ed51d2
egroupware/doc/REST-CalDAV-CardDAV/README.md

262 lines
12 KiB
Markdown
Raw Normal View History

Initial docu for REST API
2021-09-19 12:42:23 +02:00
# EGroupware CalDAV/CardDAV server and REST API
CalDAV/CardDAV is build on HTTP and WebDAV, implementing the following additional RFCs containing documentation of the protocol:
* [rfc4791: CalDAV: Calendaring Extensions to WebDAV](https://datatracker.ietf.org/doc/html/rfc4791)
* [rfc6638: Scheduling Extensions to CalDAV](https://datatracker.ietf.org/doc/html/rfc6638)
* [rfc6352: CardDAV: vCard Extensions to WebDAV](https://datatracker.ietf.org/doc/html/rfc6352)
* [rfc6578: Collection Synchronization for WebDAV](https://datatracker.ietf.org/doc/html/rfc6578)
* many additional extensions from former Apple Calendaring Server used by Apple clients and others
## Path / URL layout for CalDAV/CardDAV and REST is identical
One can use the following URLs relative (!) to https://example.org/egroupware/groupdav.php
- ```/``` base of Cal|Card|GroupDAV tree, only certain clients (KDE, Apple) can autodetect folders from here
- ```/principals/``` principal-collection-set for WebDAV ACL
- ```/principals/users/<username>/```
- ```/principals/groups/<groupname>/```
- ```/<username>/``` users home-set with
- ```/<username>/addressbook/``` addressbook of user or group <username> given the user has rights to view it
- ```/<current-username>/addressbook-<other-username>/``` shared addressbooks from other user or group
- ```/<current-username>/addressbook-accounts/``` all accounts current user has rights to see
- ```/<username>/calendar/``` calendar of user <username> given the user has rights to view it
- ```/<username>/calendar/?download``` download whole calendar as .ics file (GET request!)
- ```/<current-username>/calendar-<other-username>/``` shared calendar from other user or group (only current <username>!)
- ```/<username>/inbox/``` scheduling inbox of user <username>
- ```/<username>/outbox/``` scheduling outbox of user <username>
- ```/<username>/infolog/``` InfoLog's of user <username> given the user has rights to view it
- ```/addressbook/``` all addressbooks current user has rights to, announced as directory-gateway now
- ```/addressbook-accounts/``` all accounts current user has rights to see
- ```/calendar/``` calendar of current user
- ```/infolog/``` infologs of current user
- ```/(resources|locations)/<resource-name>/calendar``` calendar of a resource/location, if user has rights to view
- ```/<current-username>/(resource|location)-<resource-name>``` shared calendar from a resource/location
Shared addressbooks or calendars are only shown in the users home-set, if he subscribed to it via his CalDAV preferences!
Calling one of the above collections with a GET request / regular browser generates an automatic index
from the data of a allprop PROPFIND, allow browsing CalDAV/CardDAV tree with a regular browser.
## REST API: using EGroupware CalDAV/CardDAV server with JSON
> currently implemented only for contacts!
Following RFCs / drafts used/planned for JSON encoding of ressources
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
* [draft-ietf-jmap-jscontact: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-07) ([*](#implemented-changes-to-jscontact-draft-07-from-next-draft))
* [draft-ietf-jmap-jscontact-vcard-06: JSContact: Converting from and to vCard](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-vcard/)
Initial docu for REST API
2021-09-19 12:42:23 +02:00
* [rfc8984: JSCalendar: A JSON Representation of Calendar Data](https://datatracker.ietf.org/doc/html/rfc8984)
### Supported request methods and examples
* **GET** to collections with an ```Accept: application/json``` header return all resources (similar to WebDAV PROPFIND)
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: Getting all entries of a given users addessbook</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
```
curl https://example.org/egroupware/groupdav.php/<username>/addressbook/ -H "Accept: application/pretty+json" --user <username>
{
"responses": {
"/<username>/addressbook/1833": {
"uid": "5638-8623c4830472a8ede9f9f8b30d435ea4",
"prodId": "EGroupware Addressbook 21.1.001",
"created": "2010-10-21T09:55:42Z",
"updated": "2014-06-02T14:45:24Z",
"name": [
{ "type": "personal", "value": "Default" },
{ "type": "surname", "value": "Tester" }
],
"fullName": { "value": "Default Tester" },
"organizations": {
"org": {
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"name": "default.org",
Initial docu for REST API
2021-09-19 12:42:23 +02:00
"units": {
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"org_unit": "department.default.org"
Initial docu for REST API
2021-09-19 12:42:23 +02:00
}
}
},
"emails": {
"work": { "email": "test@test.com", "contexts": { "work": true }, "pref": 1 }
},
"phones": {
"tel_work": { "phone": "+49 123 4567890", "pref": 1, "features": { "voice": true }, "contexts": { "work": true } },
"tel_cell": { "phone": "012 3723567", "features": { "cell": true }, "contexts": { "work": true } }
},
"online": {
"url": { "resource": "https://www.test.com/", "type": "uri", "contexts": { "work": true } }
},
"notes": [
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"Test test TEST\n\\server\\share\n\\\nother\nblah"
Initial docu for REST API
2021-09-19 12:42:23 +02:00
],
},
"/<username>/addressbook/list-36": {
"uid": "dfa5cac5-987b-448b-85d7-6c8b529a835c",
"name": "Example distribution list",
"card": {
"uid": "dfa5cac5-987b-448b-85d7-6c8b529a835c",
"prodId": "EGroupware Addressbook 21.1.001",
"updated": "2018-04-11T14:46:43Z",
"fullName": { "value": "Example distribution list" }
},
"members": {
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"urn:uuid:5638-8623c4830472a8ede9f9f8b30d435ea4": true
Initial docu for REST API
2021-09-19 12:42:23 +02:00
}
}
}
}
```
</details>
following GET parameters are supported to customize the returned properties:
- props[]=<DAV-prop-name> eg. props[]=getetag to return only the ETAG (multiple DAV properties can be specified)
Default for addressbook collections is to only return address-data (JsContact), other collections return all props.
- sync-token=<token> to only request change since last sync-token, like rfc6578 sync-collection REPORT
- nresults=N limit number of responses (only for sync-collection / given sync-token parameter!)
this will return a "more-results"=true attribute and a new "sync-token" attribute to query for the next chunk
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: Getting just ETAGs and displayname of all contacts in a given AB</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
```
curl -i 'https://example.org/egroupware/groupdav.php/<username>/addressbook/?props[]=getetag&props[]=displayname' -H "Accept: application/pretty+json" --user <username>
{
"responses": {
"/addressbook/1833": {
"displayname": "Default Tester",
"getetag": "\"1833:24\""
},
"/addressbook/1838": {
"displayname": "Test Tester",
"getetag": "\"1838:19\""
}
}
}
```
</details>
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: Start using a sync-token to get only changed entries since last sync</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
#### Initial request with empty sync-token and only requesting 10 entries per chunk:
```
curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=&nresults=10&props[]=displayname' -H "Accept: application/pretty+json" --user <username>
{
"responses": {
"/addressbook/2050": "Frau Margot Test-Notifikation",
"/addressbook/2384": "Test Tester",
"/addressbook/5462": "Margot Testgedöns",
"/addressbook/2380": "Frau Test Defaulterin",
"/addressbook/5474": "Noch ein Neuer",
"/addressbook/5575": "Mr New Name",
"/addressbook/5461": "Herr Hugo Kurt Müller Senior",
"/addressbook/5601": "Steve Jobs",
"/addressbook/5603": "Ralf Becker",
"/addressbook/1838": "Test Tester"
},
"more-results": true,
"sync-token": "https://example.org/egroupware/groupdav.php/addressbook/1400867824"
}
```
#### Requesting next chunk:
```
curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https://example.org/egroupware/groupdav.php/addressbook/1400867824&nresults=10&props[]=displayname' -H "Accept: application/pretty+json" --user <username>
{
"responses": {
"/addressbook/1833": "Default Tester",
"/addressbook/5597": "Neuer Testschnuffi",
"/addressbook/5593": "Muster Max",
"/addressbook/5628": "2. Test Contact",
"/addressbook/5629": "Testen Tester",
"/addressbook/5630": "Testen Tester",
"/addressbook/5633": "Testen Tester",
"/addressbook/5635": "Test4 Tester",
"/addressbook/5638": "Test Kontakt",
"/addressbook/5636": "Test Default"
},
"more-results": true,
"sync-token": "https://example.org/egroupware/groupdav.php/addressbook/1427103057"
}
```
</details>
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: Requesting only changes since last sync</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
Update README.md
2021-09-20 08:34:41 +02:00
#### ```sync-token``` from last sync need to be specified (note the null for a deleted resource!)
Initial docu for REST API
2021-09-19 12:42:23 +02:00
```
curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https://example.org/egroupware/groupdav.php/addressbook/1400867824' -H "Accept: application/pretty+json" --user <username>
{
"responses": {
"/addressbook/5597": null,
"/addressbook/5593": {
"uid": "5638-8623c4830472a8ede9f9f8b30d435ea4",
"prodId": "EGroupware Addressbook 21.1.001",
"created": "2010-10-21T09:55:42Z",
"updated": "2014-06-02T14:45:24Z",
"name": [
{ "type": "personal", "value": "Default" },
{ "type": "surname", "value": "Tester" }
],
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"fullName": "Default Tester",
Initial docu for REST API
2021-09-19 12:42:23 +02:00
....
}
},
"sync-token": "https://example.org/egroupware/groupdav.php/addressbook/1427103057"
}
```
</details>
Update README.md
2021-09-20 08:34:41 +02:00
* **GET** requests with an ```Accept: application/json``` header can be used to retrieve single resources / JsContact or JsCalendar schema
Initial docu for REST API
2021-09-19 12:42:23 +02:00
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: GET request for a single resource</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
```
curl 'https://example.org/egroupware/groupdav.php/addressbook/5593' -H "Accept: application/pretty+json" --user <username>
{
"uid": "5638-8623c4830472a8ede9f9f8b30d435ea4",
"prodId": "EGroupware Addressbook 21.1.001",
"created": "2010-10-21T09:55:42Z",
"updated": "2014-06-02T14:45:24Z",
"name": [
{ "type": "personal", "value": "Default" },
{ "type": "surname", "value": "Tester" }
],
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
"fullName": "Default Tester",
Initial docu for REST API
2021-09-19 12:42:23 +02:00
....
}
```
</details>
Update README.md
2021-09-20 08:35:31 +02:00
* **POST** requests to collection with a ```Content-Type: application/json``` header add new entries in addressbook or calendar collections
Initial docu for REST API
2021-09-19 12:42:23 +02:00
(Location header in response gives URL of new resource)
<details>
Update README.md
2021-09-20 08:34:41 +02:00
<summary>Example: POST request to create a new resource</summary>
Initial docu for REST API
2021-09-19 12:42:23 +02:00
```
cat <<EOF | curl -i 'https://example.org/egroupware/groupdav.php/<username>/addressbook/' -X POST -d @- -H "Content-Type: application/json" --user <username>
{
"uid": "5638-8623c4830472a8ede9f9f8b30d435ea4",
"prodId": "EGroupware Addressbook 21.1.001",
"created": "2010-10-21T09:55:42Z",
"updated": "2014-06-02T14:45:24Z",
"name": [
{ "type": "personal", "value": "Default" },
{ "type": "surname", "value": "Tester" }
],
"fullName": { "value": "Default Tester" },
....
}
EOF
HTTP/1.1 201 Created
Location: https://example.org/egroupware/groupdav.php/<username>/addressbook/1234
```
</details>
Update README.md
2021-09-20 08:34:41 +02:00
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying single resources
Initial docu for REST API
2021-09-19 12:42:23 +02:00
* **DELETE** requests delete single resources
* one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON eg. for debugging and exploring the API
Contacts REST API: - implement missing PUT/POST of distribution list / CardGroups - implement changes from next JsContact draft: + string plus extra localizations attribute instead of localizedString object + use "<domain>:<name>" for vendor attributes - add/parse urn:uuid: prefix if UID is a UUID
2021-09-20 16:01:22 +02:00
#### Implemented changes to [JsContact draft 07](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-07) from next draft:
* localizedString type / object is removed in favor or regular String type and a [localizations object like in JsCalendar](https://datatracker.ietf.org/doc/html/rfc8984#section-4.6.1)
* [Vendor-specific Property Extensions and Values](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-07#section-1.3) use ```<domain-name>:<name>``` like in JsCalendar
Reference in New Issue Copy Permalink