Avii/Radicale
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

sharing/doc: cosmetic review

Browse Source
This commit is contained in:
Peter Bieringer
2026-04-08 22:12:03 +02:00
parent eae9dbefb1
commit 35a09300a6
1 changed files with 69 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
SHARING.md
View File

@@ -45,9 +45,9 @@ Types of supported sharing configuration:
* `Properties`: overlay properties (limited set whitelisted) * `Properties`: overlay properties (limited set whitelisted)
* `Actions`: (reserved for future usage) * `Actions`: (reserved for future usage)
`Enabled*`: owner AND user have to enable a share to become usable `Enabled*`: _owner_ AND _user_ have to enable a share to become usable
`Hidden*`: owner AND user have to disable a share to become visible in PROPFIND `Hidden*`: _owner_ AND _user_ have to disable a share to become visible in PROPFIND
#### Supported Conversions #### Supported Conversions
@@ -211,9 +211,7 @@ Note: requests to not enabled or not even defined tokens will resul tin _401 Not
* enable token as owner (can be combined with "create") * enable token as owner (can be combined with "create")
* handover URI with token to client * handover URI with token to client
## Sharing Configuration Management API ## Sharing Configuration Management API version 1
### Sharing Configuration Management API version 1
Type: POST API Type: POST API
@@ -221,16 +219,16 @@ Base-URI: `/.sharing/v1/<ShareType>/<Hook>`
See also test cases in `radicale/tests/test_sharing.py` See also test cases in `radicale/tests/test_sharing.py`
#### Data Format ### Data Format
##### Input Data Format #### Input Data Format
Parsing be controlled by `CONTENT_TYPE` Parsing be controlled by `CONTENT_TYPE`
* application/x-www-form-urlencoded * application/x-www-form-urlencoded
* application/json * application/json
##### Output Data Format #### Output Data Format
Can be selected by `HTTP_ACCEPT` - default is equal to provided `CONTENT_TYPE` Can be selected by `HTTP_ACCEPT` - default is equal to provided `CONTENT_TYPE`
@@ -238,7 +236,7 @@ Can be selected by `HTTP_ACCEPT` - default is equal to provided `CONTENT_TYPE`
* text/csv (only for "list") * text/csv (only for "list")
* application/json * application/json
##### Accepted Input Data Fields #### Accepted Input Data Fields
* `PathOrToken`: token or "virtual" collection * `PathOrToken`: token or "virtual" collection
* `PathMapped`: target collection * `PathMapped`: target collection
@@ -249,9 +247,9 @@ Can be selected by `HTTP_ACCEPT` - default is equal to provided `CONTENT_TYPE`
* `Hidden`: owner/user selected by authentication * `Hidden`: owner/user selected by authentication
* `Properties`: properties to overlay * `Properties`: properties to overlay
#### API Hooks ### API Hooks
##### API Hook "info" #### API Hook "info"
Shows what is active/supported like ShareTypes(Feature), Conversions or permission to create or use properties overlay (depending on config options) Shows what is active/supported like ShareTypes(Feature), Conversions or permission to create or use properties overlay (depending on config options)
@@ -259,7 +257,7 @@ Shows what is active/supported like ShareTypes(Feature), Conversions or permissi
* Examples * Examples
* form->text ###### form->text
```bash ```bash
curl -u user:$userpw -H "accept: text/plain" -d "" http://localhost:5232/.sharing/v1/all/info curl -u user:$userpw -H "accept: text/plain" -d "" http://localhost:5232/.sharing/v1/all/info
@@ -274,7 +272,7 @@ PermittedPropertiesOverlay=True
SupportedPropertiesOverlay=(C:calendar-description ICAL:calendar-color CR:addressbook-description INF:addressbook-color D:displayname) SupportedPropertiesOverlay=(C:calendar-description ICAL:calendar-color CR:addressbook-description INF:addressbook-color D:displayname)
``` ```
* json->json, parsed with `jq` ###### json->json, parsed with jq
``` ```
bash bash
@@ -292,12 +290,12 @@ curl -u user:$userpw --silent -H "accept: application/json" -d "" http://localho
} }
``` ```
##### API Hook "(token|map)/create" #### API Hook "(token|map)/create"
* Authorization * Authorization
* Authenticated user is `Owner` * Authenticated user is `Owner`
###### API Hook "token/create" ##### API Hook "token/create"
Create a share by mapping a collection of an `Owner` to a token. Create a share by mapping a collection of an `Owner` to a token.
@@ -322,11 +320,12 @@ Create a share by mapping a collection of an `Owner` to a token.
* Output: text/plain|application/json * Output: text/plain|application/json
| Parameter | Type | Value | | Parameter | Type | Value |
| - | - | | - | - | - |
| PathOrToken | str | (autogenerated token) | | PathOrToken | str | (autogenerated token) |
* Examples: * Examples:
* form->text
###### form->text
```bash ```bash
curl -u user:$userpw -d "PathMapped=/user/testcalendar1/" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/token/create curl -u user:$userpw -d "PathMapped=/user/testcalendar1/" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/token/create
@@ -335,14 +334,14 @@ Status='success'
PathOrToken='/.token/v1/VQR7AmsVRi2ZlFj_JwGpFx-ES5Goyku-gP_YkLh1zUw0/' PathOrToken='/.token/v1/VQR7AmsVRi2ZlFj_JwGpFx-ES5Goyku-gP_YkLh1zUw0/'
``` ```
* json->json ###### json->json
```bash ```bash
curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathMapped": "/user/testcalendar1/", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/token/create curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathMapped": "/user/testcalendar1/", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/token/create
{"ApiVersion": 1, "Status": "success", "PathOrToken": "/.token/v1/aMsmGqOsRwSH-2-6tEa8EMr4RMYzMU7WvPmjnp5qDnw0/"} {"ApiVersion": 1, "Status": "success", "PathOrToken": "/.token/v1/aMsmGqOsRwSH-2-6tEa8EMr4RMYzMU7WvPmjnp5qDnw0/"}
``` ```
###### API Hook "map/create" ##### API Hook "map/create"
Create a share by mapping a collection of an `Owner` to an `User`. Create a share by mapping a collection of an `Owner` to an `User`.
@@ -357,7 +356,7 @@ Create a share by mapping a collection of an `Owner` to an `User`.
* Input * Input
| Parameter | Type | Requirement | | Parameter | Type | Requirement |
| - | - | | - | - | - |
| PathOrToken | str | mandatory | | PathOrToken | str | mandatory |
| PathMapped | str | mandatory | | PathMapped | str | mandatory |
| Conversion | str | optional(default:none) | | Conversion | str | optional(default:none) |
@@ -370,7 +369,8 @@ Create a share by mapping a collection of an `Owner` to an `User`.
* Output: text/plain|application/json * Output: text/plain|application/json
* Examples: * Examples:
* form->text
###### form->text
```bash ```bash
curl -u owner:$ownerpw -d "PathOrToken=/user/cal1-from-owner/" -d "PathMapped=/owner/testcalendar1/" -d "User=user" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/map/create curl -u owner:$ownerpw -d "PathOrToken=/user/cal1-from-owner/" -d "PathMapped=/owner/testcalendar1/" -d "User=user" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/map/create
@@ -378,14 +378,14 @@ ApiVersion=1
Status='success' Status='success'
``` ```
* json->json ###### json->json
```bash ```bash
curl -u owner:$ownerpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/", "PathMapped": "/owner/testcalendar1/", "User" : "user", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/map/create curl -u owner:$ownerpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/", "PathMapped": "/owner/testcalendar1/", "User" : "user", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/map/create
{"ApiVersion": 1, "Status": "success"} {"ApiVersion": 1, "Status": "success"}
``` ```
##### API Hook "(all|token|map)/list" #### API Hook "(all|token|map)/list"
List shares (optional with filter) either owned or assigned as user. List shares (optional with filter) either owned or assigned as user.
@@ -403,7 +403,7 @@ List shares (optional with filter) either owned or assigned as user.
* Examples * Examples
* form->text ("all") ###### form->text ("all")
```bash ```bash
curl -u user:$userpw -d "" http://localhost:5232/.sharing/v1/map/list://localhost:5232/.sharing/v1/map/list curl -u user:$userpw -d "" http://localhost:5232/.sharing/v1/map/list://localhost:5232/.sharing/v1/map/list
@@ -414,7 +414,7 @@ Fields="ShareType;PathOrToken;PathMapped;Owner;User;Permissions;EnabledByOwner;E
Content[0]="map;/user/cal1-from-owner/;/owner/testcalendar1/;owner;user;r;True;True;False;False;1772748001;1772748163; Content[0]="map;/user/cal1-from-owner/;/owner/testcalendar1/;owner;user;r;True;True;False;False;1772748001;1772748163;
``` ```
* form->csv ("map" only) ###### form->csv ("map" only)
```bash ```bash
curl -H "accept: text/csv" -u user:$userpw -d "" http://localhost:5232/.sharing/v1/map/list://localhost:5232/.sharing/v1/map/list curl -H "accept: text/csv" -u user:$userpw -d "" http://localhost:5232/.sharing/v1/map/list://localhost:5232/.sharing/v1/map/list
@@ -422,7 +422,7 @@ ShareType;PathOrToken;PathMapped;Owner;User;Permissions;EnabledByOwner;EnabledBy
map;/user/cal1-from-owner/;/owner/testcalendar1/;owner;user;r;True;False;False;True;1772747277;1772747277; map;/user/cal1-from-owner/;/owner/testcalendar1/;owner;user;r;True;False;False;True;1772747277;1772747277;
``` ```
* json->json ("all"), parsed with `jq` ###### json->json ("all"), parsed with `jq`
```bash ```bash
curl -s -H "Content-Type: application/json" -u user:$userpw -d "{}" http://localhost:5232/.sharing/v1/all/list | jq curl -s -H "Content-Type: application/json" -u user:$userpw -d "{}" http://localhost:5232/.sharing/v1/all/list | jq
@@ -466,7 +466,7 @@ curl -s -H "Content-Type: application/json" -u user:$userpw -d "{}" http://local
``` ```
##### API Hook "(token|map)/delete" #### API Hook "(token|map)/delete"
Delete a share selected by `PathOrToken`. Delete a share selected by `PathOrToken`.
@@ -484,7 +484,7 @@ Delete a share selected by `PathOrToken`.
* Examples: * Examples:
* form->text ###### form->text
```bash ```bash
curl -u owner:$ownerpw -d "PathOrToken=/user/cal1-from-owner/" http://localhost:5232/.sharing/v1/map/delete curl -u owner:$ownerpw -d "PathOrToken=/user/cal1-from-owner/" http://localhost:5232/.sharing/v1/map/delete
@@ -492,14 +492,14 @@ ApiVersion=1
Status='success' Status='success'
``` ```
* json->json ###### json->json
```bash ```bash
curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "v1/DUSl_J5rRlWx3fy8YRXpH22FFllplkOTpcSwfGtpvkc="}' http://localhost:5232/.sharing/v1/token/delete curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "v1/DUSl_J5rRlWx3fy8YRXpH22FFllplkOTpcSwfGtpvkc="}' http://localhost:5232/.sharing/v1/token/delete
{"ApiVersion": 1, "Status": "success"} {"ApiVersion": 1, "Status": "success"}
``` ```
##### API Hook "(token|map)/update" #### API Hook "(token|map)/update"
Update a share selected by `PathOrToken`. Update a share selected by `PathOrToken`.
@@ -524,7 +524,7 @@ Execute delete+create in case `PathOrToken` needs to be changed.
* Examples: * Examples:
* form->text ###### form->text
```bash ```bash
curl -u user:$userpw -d "PathOrToken=/user/cal1-from-owner/" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/map/update curl -u user:$userpw -d "PathOrToken=/user/cal1-from-owner/" -d "Enabled=True" -d "Hidden=False" http://localhost:5232/.sharing/v1/map/update
@@ -532,14 +532,14 @@ ApiVersion=1
Status='success' Status='success'
``` ```
* json->json ###### json->json
```bash ```bash
curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/map/update curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/", "Enabled": true, "Hidden": false}' http://localhost:5232/.sharing/v1/map/update
{"ApiVersion": 1, "Status": "success"} {"ApiVersion": 1, "Status": "success"}
``` ```
##### API Hooks "(token|map)/(enable|disable|hide|unhide)" #### API Hooks "(token|map)/(enable|disable|hide|unhide)"
Toggle enable|disable|hide|unhide of `Owner` or `User` of a share selected by `PathOrToken` Toggle enable|disable|hide|unhide of `Owner` or `User` of a share selected by `PathOrToken`
@@ -555,15 +555,15 @@ Toggle enable|disable|hide|unhide of `Owner` or `User` of a share selected by `P
* Output: text/plain|application/json * Output: text/plain|application/json
* form->text ###### form->text
```bash ```bash
curl -u user:$userpw -d "PathOrToken=/user/cal1-from-owner/" http://localhost:5232/.sharing/v1/map/enable curl -u user:$userpw -d "PathOrToken=/user/cal1-from-owner/" http://localhost:5232/.sharing/v1/map/enable
ApiVersion=1 ApiVersion=1
Status='success' Status='success'
```bash ```
* json->json ###### json->json
```bash ```bash
curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/"}' http://localhost:5232/.sharing/v1/map/unhide curl -u user:$userpw -H "Content-Type: application/json" -d '{ "PathOrToken": "/user/cal1-from-owner/"}' http://localhost:5232/.sharing/v1/map/unhide