[API Request] Shares

[x1arch]

Type of change

API Clarification

Proposal description

Categories: Sharing

Update shares methods for make it more usable.

If we apply this updates, then we can use any front for shares (not only which knows about the backend). We can build share URL on the front, as example: https://xonic-ui.netlify.app/s/xteYF32ru?srv=https://demo.navidrome.org

• https://xonic-ui.netlify.app - frontend domain (which do not know anything about backend, but it can play share)
• /s/ - path to share section
• xteYF32ru - ID of the share
• ?srv=https://demo.navidrome.org - domain of share (if frontend doesn't know anything about backend)

Of course this is applicable for web versions only, for mobile applications we have URL from backend.

Backward compatibility impact

I can found only one backend (server) witch implement shares - this is navidrome For getting share they use internal methods (actually for there web client they use internal methods). I already was add share support to xonic-ui (fork of airsonic-refix). And I have a plan to add shares support in to gonic, maybe to navidrome.

Backward compatibility

• No backward compatibility impact.

API details

Existing methods modify

GET /rest/createShare

Current Parameters

Parameter	Req.	OpenS.	Default	Comment
id	Yes			ID of a song, album or video to share. Use one id parameter for each entry to share.
description	No			A user-defined description that will be displayed to people visiting the shared media.
expires	No			The time at which the share expires. Given as milliseconds since 1970.

Will be add

Parameter	Req.	OpenS.	Default	Comment
secret	No			Protect share by secret phrase (aka password).
download	No		true	Allow download songs from share or not.

Return value

Will add two params to response:

• protected - show protected it by secret phrase or not
• download - show allow download songs or not

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true
    "shares": {
      "share": [
        {
          "id": "12",
          "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
          "description": "Forget and Remember (Comfort Fit)",
          "username": "user",
          "created": "2023-03-16T04:13:09+00:00",
          "visitCount": 0,
          "protected": false,
          "download": true,
          "entry": [ ]
        }
      ]
    }
  }
}

GET /rest/updateShare

Current Parameters

Parameter	Req.	OpenS.	Default	Comment
id	Yes			ID of the share to update.
description	No			A user-defined description that will be displayed to people visiting the shared media.
expires	No			The time at which the share expires. Given as milliseconds since 1970.

Will be add

Parameter	Req.	OpenS.	Default	Comment
secret	No			Protect share by secret phrase (aka password).
download	No			Allow download songs from share or not.
add	No			ID of a song, album or video for add to share. Use one add parameter for each entry to add to share.
remove	No			ID of a song, album or video for remove it from share. Use one remove parameter for each entry to remove it from share.

Add new methods

GET /rest/getShare

Parameters

Parameter	Req.	OpenS.	Default	Comment
id	Yes			ID of the share.

Return value

Return one share

GET /rest/getSharePublic

Request should be available without authentication. Only by protection phrase (if setted).

Parameters

Parameter	Req.	OpenS.	Default	Comment
id	Yes			ID of the share.
secret	No			The secret phrase for access to share (if setted).

Return value

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true
    "share": {
        "id": "12",
        "url": "http://localhost:8989/share.php?id=12&secret=fXlKyEv3",
        "description": "Forget and Remember (Comfort Fit)",
        "username": "user",
        "created": "2023-03-16T04:13:09+00:00",
        "visitCount": 0,
        "protected": false,
        "download": true,
        "entry": [ ]
    }
  }
}

GET /rest/streamSharePublic

Request should be available without authentication. Only by protection phrase (if setted).

Parameters

Parameter	Req.	OpenS.	Default	Comment
shareId	Yes			ID of the share.
secret	No			The secret phrase for access to share (if setted).

and other stream params

Return value

The same as stream

GET /rest/getCoverArtSharePublic

Request should be available without authentication. Only by protection phrase (if setted).

Parameters

Parameter	Req.	OpenS.	Default	Comment
shareId	Yes			ID of the share.
secret	No			The secret phrase for access to share (if setted).

and other getCoverArt params

Return value

The same as getCoverArt

Security impacts

Brute-force share protection phrase, but this is can be solved by add IP to ban after a few wrong requests about to 1 hour.

Potential issues

No response

Alternative solutions

No response

[epoupon]

I am not familiar with these endpoints: I wonder if in the original Subsonic API, a share can be only modified by the user who created it?
In multi-user scenarios, it may be a good idea to isolate shares so that one user can't list/modify others' shares (accidentally or not).

[x1arch]

In original subsonic (in the demo) I do not found shares. Share contains username, that's mean we have relation with user, i suppose only user which was create share can change it.