holm/egroupware
1
1
Fork 0
forked from extern/egroupware
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
Ralf Becker 2021-09-20 08:34:41 +02:00 committed by GitHub
parent 4bb8b6d4a4
commit 2512cffe3b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 10 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -41,14 +41,14 @@ from the data of a allprop PROPFIND, allow browsing CalDAV/CardDAV tree with a r
> currently implemented only for contacts!
Following RFCs / drafts used/planned for JSON encoding of ressources
* [draft-ietf-jmap-jscontact: JSContact: A JSON representation of contact data](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-07)
* [draft-ietf-jmap-jscontact: JSContact: A JSON Representation of Contact Data](https://datatracker.ietf.org/doc/html/draft-ietf-jmap-jscontact-07)
* [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>
<summary>Getting all entries of a given users addessbook</summary>
<summary>Example: Getting all entries of a given users addessbook</summary>
```
curl https://example.org/egroupware/groupdav.php/<username>/addressbook/ -H "Accept: application/pretty+json" --user <username>
@ -112,7 +112,7 @@ curl https://example.org/egroupware/groupdav.php/<username>/addressbook/ -H "Acc
this will return a "more-results"=true attribute and a new "sync-token" attribute to query for the next chunk
<details>
<summary>Getting just ETAGs and displayname of all contacts in a given AB</summary>
<summary>Example: Getting just ETAGs and displayname of all contacts in a given AB</summary>
```
curl -i 'https://example.org/egroupware/groupdav.php/<username>/addressbook/?props[]=getetag&props[]=displayname' -H "Accept: application/pretty+json" --user <username>
@ -132,7 +132,7 @@ curl -i 'https://example.org/egroupware/groupdav.php/<username>/addressbook/?pro
</details>
<details>
<summary>Start using a sync-token to get only changed entries since last sync</summary>
<summary>Example: Start using a sync-token to get only changed entries since last sync</summary>
#### Initial request with empty sync-token and only requesting 10 entries per chunk:
```
@ -177,9 +177,9 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https:
</details>
<details>
<summary>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 deleted entries!)
#### ```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>
{
@ -203,9 +203,9 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/?sync-token=https:
```
</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>
<summary>Example GET request</summary>
<summary>Example: GET request for a single resource</summary>
```
curl 'https://example.org/egroupware/groupdav.php/addressbook/5593' -H "Accept: application/pretty+json" --user <username>
@ -227,7 +227,7 @@ curl 'https://example.org/egroupware/groupdav.php/addressbook/5593' -H "Accept:
* **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)
<details>
<summary>Example POST request</summary>
<summary>Example: POST request to create a new resource</summary>
```
cat <<EOF | curl -i 'https://example.org/egroupware/groupdav.php/<username>/addressbook/' -X POST -d @- -H "Content-Type: application/json" --user <username>
@ -250,11 +250,8 @@ Location: https://example.org/egroupware/groupdav.php/<username>/addressbook/123
```
</details>
* **PUT** requests with a "Content-Type: application/json" header allow modifying single resources
* **PUT** requests with a ```Content-Type: application/json``` header allow modifying 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
Permanent error_log() calls should use groupdav->log($str) instead, to be send to PHP error_log()
and our request-log (prefixed with "### " after request and response, like exceptions).