{
"id": long,
"href": string,
"shared_entity": EntityId Resource,
"sharer": LongIdLinkPair Resource,
"recipient": ShareRecipient Resource,
"days_to_expire": long,
"expiration": iso_8601_date,
"comment": string,
"access": Access Resource
}
{
"type": string ("user", "group", "external_user", "public", "public_link"),
"id": long,
"email": string
}
Each file and folder has a "shares" related link that can be used to get sharing information by the authenticated user. For folders, the href is "/folders/{id}/shares" and for files, it is "/folder_entries/{owning_folder_entry_id}/shares".
[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares
[Response]
{
"first":0,
"count":1,
"total":1,
"items":[{
"id":8,
"href":"/shares/8",
"comment":"",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"id":34,"type":"user","href":"/users/34"},
"sharing_date":"2016-02-29T16:16:31Z",
"access":{
"role":"EDITOR",
"sharing":{
"internal":false,
"external":false,
"public":false,
"public_link":false,
"grant_reshare":false
}
}
}]
}
Each file and folder has an "access" related link that can be used to determine whether the authenticated user can share the file or folder. For folders, the href is "/folders/{id}/access" and for files, it is "/folder_entries/{owning_folder_entry_id}/access".
[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/folder_entries/15/access
[Response]
{
"role":"EDITOR",
"sharing":{
"internal":true,
"external":true,
"public":true,
"public_link":true,
"grant_reshare":true
}
}
The Access object above indicates that the user is allowed to share the file with internal users, external users and the public. The user is also allowed to share the file's public link and grant permission to others to reshare the file.
There are also system settings that affect who the user can share with. These settings can be found in the zone config (href: "/zone_config"):
[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/zone_config
[Response]
{
...
"allow_sharing_with_ldap_groups":true,
"external_sharing_restrictions":{"mode":"none","email_list":[],"domain_list":[]},
...
}
These values indicate that the user is allowed to share with LDAP groups and that there are no restrictions in place for sharing with external users. The other possible external sharing restriction modes are "whitelist" and "blacklist". "whitelist" means that the "email_list" and "domain_list" properties contain a list of allowed email addresses and allowed email domains. Users cannot share with any other email addresses. "blacklist" means that the "email_list" and "domain_list" properties contain a list of disallowed email addresses and disallowed email domains. Users may share with all other email addresses.
To share a file or folder with a user or group, POST a Share object to the file or folder's "shares" related link. At a minimum, you must specify the recipient and the access role ("VIEWER", "EDITOR" or "CONTRIBUTOR"):
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"user","id":32},"access":{"role":"EDITOR"}}'
[Response]
{
"id":9,
"href":"/shares/9",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"id":32,"type":"user","href":"/users/32"},
"sharing_date":"2016-02-29T23:20:06Z",
"access":{
"role":"EDITOR",
"sharing":{
"internal":false,
"external":false,
"public":false,
"public_link":false,
"grant_reshare":false
}
},
}
You can grant the recipient permission to reshare the item (assuming you have permission to grant reshare) by including the desired sharing permissions in the Access property.
You can set an expiration time on the share in one of two ways. You can specify the "days_to_expire" property in the share that you post, or you can set the exact expiration date and time in the "expiration" property. For example:
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"user","id":32},"access":{"role":"EDITOR"},"days_to_expire":10}'
[Response]
{
"id":11,
"href":"/shares/11",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"id":32,"type":"user","href":"/users/32"},
"sharing_date":"2016-02-29T23:28:52Z",
"days_to_expire":10,
"expiration":"2016-03-10T23:28:52Z"
"access":{
"role":"EDITOR",
"sharing":{
"internal":false,
"external":false,
"public":false,
"public_link":false,
"grant_reshare":false
}
},
}
Notice that when you specify the "days_to_expire", both the "days_to_expire" and "expiration" properties are set in the response. The expiration time is calculated based on the supplied "days_to_expire" value and the "days_to_expire" value is no longer relevant. It is preserved in the Share object for informational purposes only.
To notify the recipient when creating the share, specify the "notify=true" query parameter:
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares?notify=true \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"user","id":32},"access":{"role":"EDITOR"}}'
[Response]
(Same as above, and the server will send an email to the recipient.)
Sharing with an external user is the same as sharing with internal users, except the recipient is a little different. The recipient type is "external_user" and the external user's email address is specified.
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares?notify=true \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"external_user","email":"user@fakedomain.com"},"access":{"role":"EDITOR"}}'
[Response]
{
"id":12,
"href":"/shares/9",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"id":141,"type":"external_user","href":"/users/141","email":"user@fakedomain.com"},
"sharing_date":"2016-02-29T23:20:06Z",
"access":{...}
}
The attempt to share with the external user will fail if the user does not have permission to share the file or folder with external users, or if the email address is not allowed based on the system external sharing restriction settings.
Sharing with the public is the same as sharing with internal users, except the recipient type is "public". When sharing publicly, the access role must be "VIEWER".
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares?notify=true \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"public"},"access":{"role":"VIEWER"}}'
[Response]
{
"id":13,
"href":"/shares/9",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"type":"public"},
"sharing_date":"2016-02-29T23:20:06Z",
"access":{...}
}
To create a public link for a file, the recipient type should be "public_link". You do not need to specify the access in this case. Only "VIEWER" with no sharing permissions is allowed.
The public URLs that can be used by anyone to access the file are returned in the "permalinks" property. The "download" URL is a direct link to download the file. The "view" URL goes to the file details page in the web application.
[Request]
> curl -k -u dlewis:novell \
https://amethyst.provo.novell.com:8443/rest/folder_entries/15/shares?notify=true \
-H "Content-Type: application/json" -X POST \
-d '{"recipient":{"type":"public_link"}}'
[Response]
{
"id":13,
"href":"/shares/9",
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"sharer":{"id":20,"href":"/users/20"},
"recipient":{"type":"public"},
"sharing_date":"2016-02-29T23:20:06Z",
"access":{...},
"permalinks":[{
"rel":"download",
"href":"https://amethyst.provo.novell.com:8443/ssf/s/readFile/share/15/-6714533406876790678/publicLink/test.txt"
},{
"rel":"view",
"href":"https://amethyst.provo.novell.com:8443/ssf/s/readFile/share/15/-6714533406876790678/publicLinkHtml/test.txt"
}]
}
To modify a share, POST the update share object to the share's href value ("/shares/{id}"). You are only allowed to change the share's comment, access and expiration. Modifying the recipient or shared file or folder is not supported.
[Request]
> curl -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/shares/13 \
-H "Content-Type: application/json" -X POST \
-d '{"days_to_expire":30,"access":{"role":"VIEWER"}}'
[Response]
{
"id":17,
"href":"/shares/17",
"sharer":{"id":20,"href":"/users/20"},
"shared_entity":{"id":15,"type":"folderEntry","href":"/folder_entries/15"},
"recipient":{"type":"public"},
"sharing_date":"2016-03-01T00:03:20Z",
"days_to_expire":30,
"expiration":"2016-03-31T00:03:22Z",
"access":{
"role":"VIEWER",
"sharing":{...}
}
}
Note: Modifying a share changes its ID. The new ID is returned in the response.
The recipient of the share will notified by email if the "notify=true" query parameter is specified.
You can also modify a share by creating a new share. When creating a new share, if the recipient, sharer and shared_entity match an existing share, that share is replaced with the new share.
To delete a share, send a DELETE request to the share's href value ("/shares/{id}").
[Request]
> curl -v -k -u dlewis:novell https://amethyst.provo.novell.com:8443/rest/shares/17 -X DELETE
[Response]
< HTTP/1.1 204 No Content