extern/egroupware_official
1
0
Fork 0
mirror of https://github.com/EGroupware/egroupware.git synced 2024-11-22 07:53:39 +01:00
Code Issues Packages Projects Releases Wiki Activity

replaced draft with now existing rfc URLs and unified the markup of all REST API documents

Browse Source
This commit is contained in:
ralf 2024-05-15 08:35:25 +02:00
parent a69142946c
commit 3810ea4e35
7 changed files with 107 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
doc/REST-CalDAV-CardDAV/Addressbook.md
View File

@ -6,15 +6,14 @@ Authentication is via Basic Auth with username and a password, or a token valid
- Addressbook application - Addressbook application
Following RFCs / drafts used/planned for JSON encoding of resources Following RFCs / drafts used/planned for JSON encoding of resources
* [draft-ietf-jmap-jscontact: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact) * [rfc9553: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/rfc9553)
([* see at end of document](#implemented-changes-from-jscontact-draft-08)) * [rfc9555: JSContact: Converting from and to vCard](https://datatracker.ietf.org/doc/html/rfc9555)
* [draft-ietf-jmap-jscontact-vcard: JSContact: Converting from and to vCard](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-vcard/)
* [rfc8984: JSCalendar: A JSON Representation of Calendar Data](https://datatracker.ietf.org/doc/html/rfc8984) * [rfc8984: JSCalendar: A JSON Representation of Calendar Data](https://datatracker.ietf.org/doc/html/rfc8984)
* [links sub-collection to add attachments and links to other application-entries](Links-and-attachments.md) * [links sub-collection to add attachments and links to other application-entries](Links-and-attachments.md)
### Supported request methods and examples ### Supported request methods and examples
* **GET** to collections with an ```Accept: application/json``` header return all resources (similar to WebDAV PROPFIND) #### **GET** to collections with an `Accept: application/json` header return all resources (similar to WebDAV PROPFIND)
<details> <details>
<summary>Example: Getting all entries of a given users addessbook</summary> <summary>Example: Getting all entries of a given users addessbook</summary>
@ -154,7 +153,7 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https:
<details> <details>
<summary>Example: Requesting only changes since last sync</summary> <summary>Example: Requesting only changes since last sync</summary>
#### ```sync-token``` from last sync need to be specified (note the null for a deleted resource!) #### `sync-token` from last sync need to be specified (note the null for a deleted resource!)
``` ```
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> 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>
{ {
@ -178,7 +177,7 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https:
``` ```
</details> </details>
* **GET** requests with an ```Accept: application/json``` header can be used to retrieve single resources / JsContact or JsCalendar schema #### **GET** requests with an `Accept: application/json` header can be used to retrieve single resources / JsContact or JsCalendar schema
<details> <details>
<summary>Example: GET request for a single resource showcasing available fieldes</summary> <summary>Example: GET request for a single resource showcasing available fieldes</summary>
@ -358,7 +357,7 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/6502' -H "Accept:
``` ```
</details> </details>
* **POST** requests to collection with a ```Content-Type: application/json``` header add new entries in addressbook or calendar collections #### **POST** requests to collection with a `Content-Type: application/json` header add new entries in addressbook or calendar collections
(Location header in response gives URL of new resource) (Location header in response gives URL of new resource)
<details> <details>
<summary>Example: POST request to create a new resource</summary> <summary>Example: POST request to create a new resource</summary>
@ -412,7 +411,7 @@ Location: https://example.org/egroupware/groupdav.php/<username>/addressbook/123
``` ```
</details> </details>
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying single resources (requires to specify all attributes!) #### **PUT** requests with a `Content-Type: application/json` header allow modifying single resources (requires to specify all attributes!)
<details> <details>
<summary>Example: PUT request to update a resource</summary> <summary>Example: PUT request to update a resource</summary>
@ -468,7 +467,7 @@ Location: https://example.org/egroupware/groupdav.php/<username>/addressbook/123
</details> </details>
* **PATCH** request with a ```Content-Type: application/json``` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject) #### **PATCH** request with a `Content-Type: application/json` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject)
<details> <details>
<summary>Example: PATCH request to modify a contact with partial data</summary> <summary>Example: PATCH request to modify a contact with partial data</summary>
@ -498,14 +497,14 @@ HTTP/1.1 204 No content
``` ```
</details> </details>
* **DELETE** requests delete single resources #### **DELETE** requests delete single resources
* one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON eg. for debugging and exploring the API * one can use `Accept: application/pretty+json` to receive pretty-printed JSON eg. for debugging and exploring the API
#### Implemented [changes from JsContact draft 08](https://github.com/rsto/draft-stepanek-jscontact/compare/draft-ietf-jmap-jscontact-08): #### Implemented [changes from JsContact draft 08](https://github.com/rsto/draft-stepanek-jscontact/compare/draft-ietf-jmap-jscontact-08):
* 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) * 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) * [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 use `<domain-name>:<name>` like in JsCalendar
* top-level objects need a ```@type``` attribute with one of the following values: * top-level objects need a `@type` attribute with one of the following values:
```NameComponent```, ```Organization```, ```Title```, ```Phone```, ```Resource```, ```File```, ```ContactLanguage```, `NameComponent`, `Organization`, `Title`, `Phone`, `Resource`, `File`, `ContactLanguage`,
```Address```, ```StreetComponent```, ```Anniversary```, ```PersonalInformation``` `Address`, `StreetComponent`, `Anniversary`, `PersonalInformation`

14
doc/REST-CalDAV-CardDAV/Calendar.md
View File

@ -11,7 +11,7 @@ Following RFCs / drafts used/planned for JSON encoding of resources
### Supported request methods and examples ### Supported request methods and examples
* **GET** to collections with an ```Accept: application/json``` header return all resources (similar to WebDAV PROPFIND) #### **GET** to collections with an `Accept: application/json` header return all resources (similar to WebDAV PROPFIND)
<details> <details>
<summary>Example: Getting all entries of a given users calendar</summary> <summary>Example: Getting all entries of a given users calendar</summary>
@ -211,7 +211,7 @@ following GET parameters are supported to customize the returned properties:
Examples: see addressbook Examples: see addressbook
* **GET** requests with an ```Accept: application/json``` header can be used to retrieve single resources / JsContact or JsCalendar schema #### **GET** requests with an `Accept: application/json` header can be used to retrieve single resources / JsContact or JsCalendar schema
<details> <details>
<summary>Example: GET request for a single resource</summary> <summary>Example: GET request for a single resource</summary>
@ -248,7 +248,7 @@ curl 'https://example.org/egroupware/groupdav.php/calendar/6502' -H "Accept: app
``` ```
</details> </details>
* **POST** requests to collection with a ```Content-Type: application/json``` header add new entries in addressbook or calendar collections #### **POST** requests to collection with a `Content-Type: application/json` header add new entries in addressbook or calendar collections
(Location header in response gives URL of new resource) (Location header in response gives URL of new resource)
<details> <details>
<summary>Example: POST request to create a new resource and use "Prefer: return=representation" to get it fully expanded back</summary> <summary>Example: POST request to create a new resource and use "Prefer: return=representation" to get it fully expanded back</summary>
@ -300,7 +300,7 @@ X-WebDAV-Status: 201 Created
``` ```
</details> </details>
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying single resources (requires to specify all attributes!) #### **PUT** requests with a `Content-Type: application/json` header allow modifying single resources (requires to specify all attributes!)
<details> <details>
<summary>Example: PUT request with UID to update an existing resource or create it, if not exists</summary> <summary>Example: PUT request with UID to update an existing resource or create it, if not exists</summary>
@ -329,7 +329,7 @@ Location: https://example.org/egroupware/groupdav.php/<username>/calendar/1234
</details> </details>
* **PATCH** request with a ```Content-Type: application/json``` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject) #### **PATCH** request with a `Content-Type: application/json` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject)
<details> <details>
<summary>Example: PATCH request to modify an event with partial data</summary> <summary>Example: PATCH request to modify an event with partial data</summary>
@ -345,7 +345,7 @@ HTTP/1.1 204 No content
``` ```
</details> </details>
* **DELETE** requests delete single resources #### **DELETE** requests delete single resources
<details> <details>
<summary>Example: Delete an existing event</summary> <summary>Example: Delete an existing event</summary>
@ -358,4 +358,4 @@ HTTP/1.1 204 No Content
``` ```
</details> </details>
* one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON e.g. for debugging and exploring the API * one can use `Accept: application/pretty+json` to receive pretty-printed JSON e.g. for debugging and exploring the API

14
doc/REST-CalDAV-CardDAV/Infolog.md
View File

@ -41,7 +41,7 @@ Following RFCs / drafts used/planned for JSON encoding of InfoLog entries
### Supported request methods and examples ### Supported request methods and examples
* **GET** to collections with an ```Accept: application/json``` header return all resources (similar to WebDAV PROPFIND) #### **GET** to collections with an `Accept: application/json` header return all resources (similar to WebDAV PROPFIND)
<details> <details>
<summary>Example: Getting all entries of a given users infolog collection</summary> <summary>Example: Getting all entries of a given users infolog collection</summary>
@ -123,7 +123,7 @@ following GET parameters are supported to customize the returned properties:
Examples: see addressbook Examples: see addressbook
* **GET** requests with an ```Accept: application/json``` header can be used to retrieve single resources / JsContact or JsCalendar schema #### **GET** requests with an `Accept: application/json` header can be used to retrieve single resources / JsContact or JsCalendar schema
<details> <details>
<summary>Example: GET request for a single resource</summary> <summary>Example: GET request for a single resource</summary>
@ -201,7 +201,7 @@ curl 'https://example.org/egroupware/groupdav.php/infolog/956' -H "Accept: appli
``` ```
</details> </details>
* **POST** requests to collection with a ```Content-Type: application/json``` header add new entries in infolog collections #### **POST** requests to collection with a `Content-Type: application/json` header add new entries in infolog collections
(Location header in response gives URL of new resource) (Location header in response gives URL of new resource)
<details> <details>
<summary>Example: POST request to create a new resource and use "Prefer: return=representation" to get it fully expanded back</summary> <summary>Example: POST request to create a new resource and use "Prefer: return=representation" to get it fully expanded back</summary>
@ -268,7 +268,7 @@ X-WebDAV-Status: 201 Created
``` ```
</details> </details>
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying single resources (requires to specify all attributes!) #### **PUT** requests with a `Content-Type: application/json` header allow modifying single resources (requires to specify all attributes!)
<details> <details>
<summary>Example: PUT request with UID to update an existing resource or create it, if not exists</summary> <summary>Example: PUT request with UID to update an existing resource or create it, if not exists</summary>
@ -297,7 +297,7 @@ Location: https://example.org/egroupware/groupdav.php/<username>/infolog/1234
</details> </details>
* **PATCH** request with a ```Content-Type: application/json``` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject) #### **PATCH** request with a `Content-Type: application/json` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject)
<details> <details>
<summary>Example: PATCH request to modify an event with partial data</summary> <summary>Example: PATCH request to modify an event with partial data</summary>
@ -313,7 +313,7 @@ HTTP/1.1 204 No content
``` ```
</details> </details>
* **DELETE** requests delete single resources #### **DELETE** requests delete single resources
<details> <details>
<summary>Example: Delete an existing event</summary> <summary>Example: Delete an existing event</summary>
@ -326,4 +326,4 @@ HTTP/1.1 204 No Content
``` ```
</details> </details>
* one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON e.g. for debugging and exploring the API * one can use `Accept: application/pretty+json` to receive pretty-printed JSON e.g. for debugging and exploring the API

26
doc/REST-CalDAV-CardDAV/Links-and-attachments.md
View File

@ -10,19 +10,19 @@ Authentication is via Basic Auth with username and a password, or a token valid
### Following schema is used for JSON encoding of links and attachments ### Following schema is used for JSON encoding of links and attachments
* @type: `Link` * `@type`: `Link`
* href: string URI to linked entry or attachments * `href`: string URI to linked entry or attachments
* title: string title of link * `title`: string title of link
* contentType: string `application/json` for links, content-type of attachments * `contentType`: string `application/json` for links, content-type of attachments
* size: size of attachments * `size`: size of attachments
* egroupware.org-remark: string * `egroupware.org-remark`: string
* egroupware.org-app: string application name of the linked entry * `egroupware.org-app`: string application name of the linked entry
* egroupware.org-id: string application ID of the linked entry * `egroupware.org-id`: string application ID of the linked entry
* rel: string `egroupware.org-primary` to mark a primary link for InfoLog entries * `rel`: string `egroupware.org-primary` to mark a primary link for InfoLog entries
### Supported request methods and examples ### Supported request methods and examples
* **GET** to application entry collections to return all links and attachments #### **GET** to application entry collections to return all links and attachments
<details> <details>
<summary>Example: Getting all links and attachments of a given application entry</summary> <summary>Example: Getting all links and attachments of a given application entry</summary>
@ -62,7 +62,7 @@ Content-Type: application/json
``` ```
</details> </details>
* **POST** request to upload an attachment or link with another application entry #### **POST** request to upload an attachment or link with another application entry
<details> <details>
<summary>Example: Adding a PDF as attachment to an application entry</summary> <summary>Example: Adding a PDF as attachment to an application entry</summary>
@ -104,7 +104,7 @@ Location: https://example.org/egroupware/groupdav.php/<username>/infolog/<id>/li
> `<id>` is the numerical ID of the entry of application `<app>`, NOT the UUID some applications have! > `<id>` is the numerical ID of the entry of application `<app>`, NOT the UUID some applications have!
> `<2nd-app-id>` is also the numerical ID of `<2nd-app>`, not the UUID > `<2nd-app-id>` is also the numerical ID of `<2nd-app>`, not the UUID
* **DELETE** request to remove a link or attachment #### **DELETE** request to remove a link or attachment
<details> <details>
<summary>Example: deleting an attachment or link</summary> <summary>Example: deleting an attachment or link</summary>
@ -116,4 +116,4 @@ HTTP/1.1 201 No Content
``` ```
</details> </details>
> one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON eg. for debugging and exploring the API > one can use `Accept: application/pretty+json` to receive pretty-printed JSON eg. for debugging and exploring the API

64
doc/REST-CalDAV-CardDAV/Mail.md
View File

@ -10,7 +10,7 @@ Authentication is via Basic Auth with username and a password, or a token valid
Implemented requests (relative to https://example.org/egroupware/groupdav.php) Implemented requests (relative to https://example.org/egroupware/groupdav.php)
- ```GET /mail``` get different mail accounts available to user #### **GET** `/mail` get different mail accounts available to user
<details> <details>
<summary>Example: Querying available identities / signatures</summary> <summary>Example: Querying available identities / signatures</summary>
@ -29,29 +29,29 @@ Content-Type: application/json
``` ```
</details> </details>
- ```POST /mail[/<id>]``` send mail for default or given identity <id> #### **POST** `/mail[/<id>]` send mail for default or given identity <id>
<details> <details>
<summary>Example: Sending mail</summary> <summary>Example: Sending mail</summary>
The content of the POST request is a JSON encoded object with following attributes The content of the POST request is a JSON encoded object with following attributes
- ```to```: array of strings with (RFC882) email addresses like ```["info@egroupware.org", "Ralf Becker <rb@egroupware.org"]``` - `to`: array of strings with (RFC882) email addresses like `["info@egroupware.org", "Ralf Becker <rb@egroupware.org"]`
- ```cc```: array of strings with (RFC882) email addresses (optional) - `cc`: array of strings with (RFC882) email addresses (optional)
- ```bcc```: array of strings with (RFC882) email addresses (optional) - `bcc`: array of strings with (RFC882) email addresses (optional)
- ```replyto```: string with (RFC822) email address (optional) - `replyto`: string with (RFC822) email address (optional)
- ```subject```: string with subject - `subject`: string with subject
- ```body```: string plain text body (optional) - `body`: string plain text body (optional)
- ```bodyHtml```: string with html body (optional) - `bodyHtml`: string with html body (optional)
- ```replyEml```: string returned from uploaded eml file to reply to (optional) - `replyEml`: string returned from uploaded eml file to reply to (optional)
- ```attachments```: array of strings returned from uploaded attachments (see below) or VFS path ```["/mail/attachments/<token>", "/home/<user>/<filename>", ...]``` - `attachments`: array of strings returned from uploaded attachments (see below) or VFS path `["/mail/attachments/<token>", "/home/<user>/<filename>", ...]`
- ```attachmentType```: one of the following strings (optional, default "attach") - `attachmentType`: one of the following strings (optional, default "attach")
- "attach" send as attachment - "attach" send as attachment
- "link" send as sharing link - "link" send as sharing link
- "share_ro" send a readonly share using the current file content (VFS only) - "share_ro" send a readonly share using the current file content (VFS only)
- "share_rw" send as writable share (VFS and EPL only) - "share_rw" send as writable share (VFS and EPL only)
- ```shareExpiration```: "yyyy-mm-dd" or e.g. "+2days", default not accessed in 100 days (EPL only) - `shareExpiration`: "yyyy-mm-dd" or e.g. "+2days", default not accessed in 100 days (EPL only)
- ```sharePassword```: string with password required to access share, default none (EPL only) - `sharePassword`: string with password required to access share, default none (EPL only)
- ```folder```: folder to store send mail, default Sent folder - `folder`: folder to store send mail, default Sent folder
- ```priority```: 1: high, 3: normal (default), 5: low - `priority`: 1: high, 3: normal (default), 5: low
``` ```
curl -i https://example.org/egroupware/groupdav.php/mail --user <user> \ curl -i https://example.org/egroupware/groupdav.php/mail --user <user> \
@ -89,7 +89,7 @@ Content-Type: application/json
``` ```
</details> </details>
- ```POST /mail[/<id>]/compose``` launch compose window #### **POST** `/mail[/<id>]/compose` launch compose window
<details> <details>
<summary>Example: Opening a compose window</summary> <summary>Example: Opening a compose window</summary>
@ -116,7 +116,7 @@ Content-Type: application/json
``` ```
</details> </details>
- ```POST /mail/attachments/<filename>``` upload mail attachments #### **POST** `/mail/attachments/<filename>` upload mail attachments
<details> <details>
<summary>Example: Uploading an attachment to be used for sending or composing mail</summary> <summary>Example: Uploading an attachment to be used for sending or composing mail</summary>
@ -135,12 +135,12 @@ Location: https://example.org/egroupware/groupdav.php/mail/attachments/<token>
"location": "/mail/attachments/<token>" "location": "/mail/attachments/<token>"
} }
``` ```
> When using curl to upload attachments it's important to use ```--data-binary```, just ```-d``` or ```--data``` is NOT sufficient! > When using curl to upload attachments it's important to use `--data-binary`, just `-d` or `--data` is NOT sufficient!
> Use a `X-No-Location: true` header to get NO `Location: <url>` header with HTTP status `201 Created` back, but a simple `200 Ok`! > Use a `X-No-Location: true` header to get NO `Location: <url>` header with HTTP status `201 Created` back, but a simple `200 Ok`!
</details> </details>
- ```POST /mail[/<id>]/view``` view an eml file #### **POST** `/mail[/<id>]/view` view an eml file
<details> <details>
<summary>Example: Uploading an eml file to be viewed</summary> <summary>Example: Uploading an eml file to be viewed</summary>
@ -162,25 +162,25 @@ HTTP/1.1 200 Ok
``` ```
> You get a `404 Not Found`, if the user is NOT online, like in compose. > You get a `404 Not Found`, if the user is NOT online, like in compose.
> When using curl to upload attachments it's important to use ```--data-binary```, just ```-d``` or ```--data``` is NOT sufficient! > When using curl to upload attachments it's important to use `--data-binary`, just `-d` or `--data` is NOT sufficient!
</details> </details>
- ```POST /mail[/<id>]/vacation``` enable or disable vacation message or forwarding #### **POST** `/mail[/<id>]/vacation` enable or disable vacation message or forwarding
<details> <details>
<summary>Example: Setting a vacation message with given start- and end-date</summary> <summary>Example: Setting a vacation message with given start- and end-date</summary>
The content of the POST request is a JSON encoded object with following attributes The content of the POST request is a JSON encoded object with following attributes
- ```status```: "on" (default, if not start/end), "off" or "by_date" (default, if start/end given) - `status`: "on" (default, if not start/end), "off" or "by_date" (default, if start/end given)
- ```start```: start-date "YYYY-mm-dd", or e.g. "+2days" (optional) - `start`: start-date "YYYY-mm-dd", or e.g. "+2days" (optional)
- ```end```: end-date (last day of vacation) "YYYY-mm-dd" (optional) - `end`: end-date (last day of vacation) "YYYY-mm-dd" (optional)
- ```text```: vacation notice to the sender (can container $$start$$ and $$end$$ placeholders) - `text`: vacation notice to the sender (can container $$start$$ and $$end$$ placeholders)
- ```modus```: "notice+store" (default) send vacation notice and store in INBOX, "notice": only send notice, "store": only store - `modus`: "notice+store" (default) send vacation notice and store in INBOX, "notice": only send notice, "store": only store
- ```forwards```: array of strings with (RFC882) email addresses (optional, default no forwarding) - `forwards`: array of strings with (RFC882) email addresses (optional, default no forwarding)
- ```addresses```: array of strings with (RFC882) email addresses (optional, default primary email address only) - `addresses`: array of strings with (RFC882) email addresses (optional, default primary email address only)
- ```days```: integer, after how many days should a sender get the vacation message again (optional, otherwise default is used) - `days`: integer, after how many days should a sender get the vacation message again (optional, otherwise default is used)
> The ```POST``` request is handled like a ```PATCH```, only the given attributes are replaced, use null to unset them. > The `POST` request is handled like a `PATCH`, only the given attributes are replaced, use null to unset them.
``` ```
curl -i https://example.org/egroupware/groupdav.php/mail/vacation --user <user> -X POST -H 'Content-Type: application/json' \ curl -i https://example.org/egroupware/groupdav.php/mail/vacation --user <user> -X POST -H 'Content-Type: application/json' \
@ -195,7 +195,7 @@ HTTP/1.1 200 Ok
``` ```
</details> </details>
- ```GET /mail[/<id>]/vacation``` get current vacation message/handling #### **GET** `/mail[/<id>]/vacation` get current vacation message/handling
<details> <details>
<summary>Example: Querying the current vacation handling</summary> <summary>Example: Querying the current vacation handling</summary>

53
doc/REST-CalDAV-CardDAV/README.md
View File

@ -11,34 +11,34 @@ CalDAV/CardDAV is build on HTTP and WebDAV, implementing the following additiona
One can use the following URLs relative (!) to https://example.org/egroupware/groupdav.php 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 - `/` base of Cal|Card|GroupDAV tree, only certain clients (KDE, Apple) can autodetect folders from here
- ```/principals/``` principal-collection-set for WebDAV ACL - `/principals/` principal-collection-set for WebDAV ACL
- ```/principals/users/<username>/``` - `/principals/users/<username>/`
- ```/principals/groups/<groupname>/``` - `/principals/groups/<groupname>/`
- ```/<username>/``` users home-set with - `/<username>/` users home-set with
- ```/<username>/addressbook/``` addressbook of user or group <username> given the user has rights to view it - `/<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-<other-username>/` shared addressbooks from other user or group
- ```/<current-username>/addressbook-accounts/``` all accounts current user has rights to see - `/<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/` calendar of user <username> given the user has rights to view it
- ```/<username>/calendar/?download``` download whole calendar as .ics file (GET request!) - `/<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>!) - `/<current-username>/calendar-<other-username>/` shared calendar from other user or group (only current <username>!)
- ```/<username>/inbox/``` scheduling inbox of user <username> - `/<username>/inbox/` scheduling inbox of user <username>
- ```/<username>/outbox/``` scheduling outbox 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 - `/<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/` all addressbooks current user has rights to, announced as directory-gateway now
- ```/addressbook-accounts/``` all accounts current user has rights to see - `/addressbook-accounts/` all accounts current user has rights to see
- ```/calendar/``` calendar of current user - `/calendar/` calendar of current user
- ```/infolog/``` infologs of current user - `/infolog/` infologs of current user
- ```/(resources|locations)/<resource-name>/calendar``` calendar of a resource/location, if user has rights to view - `/(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 - `/<current-username>/(resource|location)-<resource-name>` shared calendar from a resource/location
- ```/mail/``` REST API only - `/mail/` REST API only
- ```/timesheet/``` REST API only - `/timesheet/` REST API only
- ```/smallpart/``` REST API only - `/smallpart/` REST API only
Shared addressbooks or calendars are only shown in the users home-set, if he subscribed to it via his CalDAV preferences! 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 Calling one of the above collections with a GET request / regular browser generates an automatic index
from the data of an ```allprop``` PROPFIND, allow browsing CalDAV/CardDAV tree with a regular browser. from the data of an `allprop` PROPFIND, allow browsing CalDAV/CardDAV tree with a regular browser.
## REST API: using EGroupware CalDAV/CardDAV server with JSON ## REST API: using EGroupware CalDAV/CardDAV server with JSON
- [Addressbook](Addressbook.md) - [Addressbook](Addressbook.md)
@ -61,9 +61,8 @@ from the data of an ```allprop``` PROPFIND, allow browsing CalDAV/CardDAV tree w
> a "Content-Type: application/json" header, otherwise you talk to the CalDAV/CardDAV server and don't get the response you expect! > a "Content-Type: application/json" header, otherwise you talk to the CalDAV/CardDAV server and don't get the response you expect!
Following RFCs / drafts used/planned for JSON encoding of resources Following RFCs / drafts used/planned for JSON encoding of resources
* [draft-ietf-jmap-jscontact: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact) * [rfc9553: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/rfc9553)
([* see at end of document](#implemented-changes-from-jscontact-draft-08)) * [rfc9555: JSContact: Converting from and to vCard](https://datatracker.ietf.org/doc/html/rfc9555)
* [draft-ietf-jmap-jscontact-vcard: JSContact: Converting from and to vCard](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-vcard/)
* [rfc8984: JSCalendar: A JSON Representation of Calendar Data](https://datatracker.ietf.org/doc/html/rfc8984) * [rfc8984: JSCalendar: A JSON Representation of Calendar Data](https://datatracker.ietf.org/doc/html/rfc8984)
### ToDos ### ToDos

16
doc/REST-CalDAV-CardDAV/Timesheet.md
View File

@ -29,7 +29,7 @@ Following schema is used for JSON encoding of timesheets
### Supported request methods and examples ### Supported request methods and examples
* **GET** to collections with an ```Accept: application/json``` header return all timesheets (similar to WebDAV PROPFIND) #### **GET** to collections with an `Accept: application/json` header return all timesheets (similar to WebDAV PROPFIND)
<details> <details>
<summary>Example: Getting all timesheets of a given user</summary> <summary>Example: Getting all timesheets of a given user</summary>
@ -160,7 +160,7 @@ curl 'https://example.org/egroupware/groupdav.php/timesheet/?sync-token=https://
<details> <details>
<summary>Example: Requesting only changes since last sync</summary> <summary>Example: Requesting only changes since last sync</summary>
#### ```sync-token``` from last sync need to be specified (note the null for a deleted resource!) #### `sync-token` from last sync need to be specified (note the null for a deleted resource!)
``` ```
curl 'https://example.org/egroupware/groupdav.php/timesheet/?sync-token=https://example.org/egroupware/groupdav.php/timesheet/1400867824' -H "Accept: application/pretty+json" --user <username> curl 'https://example.org/egroupware/groupdav.php/timesheet/?sync-token=https://example.org/egroupware/groupdav.php/timesheet/1400867824' -H "Accept: application/pretty+json" --user <username>
{ {
@ -176,7 +176,7 @@ curl 'https://example.org/egroupware/groupdav.php/timesheet/?sync-token=https://
``` ```
</details> </details>
* **GET** requests with an ```Accept: application/json``` header can be used to retrieve single resources / JsTimesheet schema #### **GET** requests with an `Accept: application/json` header can be used to retrieve single resources / JsTimesheet schema
<details> <details>
<summary>Example: GET request for a single resource showcasing available fieldes</summary> <summary>Example: GET request for a single resource showcasing available fieldes</summary>
@ -216,7 +216,7 @@ curl 'https://example.org/egroupware/groupdav.php/timesheet/140' -H "Accept: app
``` ```
</details> </details>
* **POST** requests to collection with a ```Content-Type: application/json``` header add new entries in timesheet collections #### **POST** requests to collection with a `Content-Type: application/json` header add new entries in timesheet collections
(Location header in response gives URL of new resource) (Location header in response gives URL of new resource)
<details> <details>
<summary>Example: POST request to create a new resource</summary> <summary>Example: POST request to create a new resource</summary>
@ -252,7 +252,7 @@ ETag: "204:1707233040"
``` ```
</details> </details>
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying single resources (requires to specify all attributes!) #### **PUT** requests with a `Content-Type: application/json` header allow modifying single resources (requires to specify all attributes!)
<details> <details>
<summary>Example: PUT request to update a resource</summary> <summary>Example: PUT request to update a resource</summary>
@ -278,7 +278,7 @@ HTTP/1.1 204 No Content
</details> </details>
* **PATCH** request with a ```Content-Type: application/json``` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject) #### **PATCH** request with a `Content-Type: application/json` header allow to modify a single resource by only specifying changed attributes as a [PatchObject](https://www.rfc-editor.org/rfc/rfc8984.html#type-PatchObject)
<details> <details>
<summary>Example: PATCH request to modify a timesheet with partial data</summary> <summary>Example: PATCH request to modify a timesheet with partial data</summary>
@ -294,7 +294,7 @@ HTTP/1.1 204 No content
``` ```
</details> </details>
* **DELETE** requests delete single resources #### **DELETE** requests delete single resources
<details> <details>
<summary>Example: DELETE request to delete a timesheet</summary> <summary>Example: DELETE request to delete a timesheet</summary>
@ -306,4 +306,4 @@ HTTP/1.1 204 No content
``` ```
</details> </details>
> one can use ```Accept: application/pretty+json``` to receive pretty-printed JSON eg. for debugging and exploring the API > one can use `Accept: application/pretty+json` to receive pretty-printed JSON eg. for debugging and exploring the API