Add collections

[ygabuev]

Follows the discussion in #73.

Add the concept of a collection with basic CRUD functionality. A collection is an ordered list of items - songs, artist, albums, playlists (other types can be added in the future). Users can create, modify and delete collections.

The proposed endpoints and schemas closely follow those for playlists, however, items don't have to be just songs. Additionally, the updateCollection endpoint has a more elaborate mechanism for adding, removing and moving items around via the add, remove, and move parameters respectively.

New methods:

• getCollections
• getCollection
• createCollection
• updateCollection
• deleteCollection

The existing methods and responses all stay the same.

There are no clear contribution guidelines, so sorry if I opened the PR prematurely without clarifying the details in the discussion. I figured that it's easier to discuss the proposal against a more concrete OpenAPI implementation.

Open questions:

• do we need more item types (podcast, internet radio, ...)?
• should users be able to share collections?
• cover art for collections?

[netlify]

✅ Deploy Preview for opensubsonic ready!

Name	Link
🔨 Latest commit	58c865f
🔍 Latest deploy log	https://app.netlify.com/projects/opensubsonic/deploys/6a198ab904f93100086cff3b
😎 Deploy Preview	https://deploy-preview-237--opensubsonic.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Tolriq]

It must be an extension, markdown first before openAPI.

With that said your API does not work for the ordered part, arrays of content per type does not allow mixed content ordering, the solution also does not properly handle duplicates and moving stuff.

Should be an array of items with mediaType mediaId probably.

[ygabuev]

@Tolriq thanks for the comment. I will provide the markdown docs soon.

You are right, the per-type arrays are wrong, I was confused by the existing semantics for parameters in the GET versions of createX endpoints. I've added a dedicated CollectionItemId schema with type and id fields (the word "media" is a bit out of place here IMO, e.g. artists are not media). Those should be used for creating and updating collections.

I've also added the extension comments and errors for the new endpoints

[ygabuev]

Hey @Tolriq. I am reworking the proposal and would appreciate some input.

I see that many of the older endpoints that manipulate data have a very particular way of using HTTP methods, e.g. createPlaylist allows GET, and deleteUser allows GET and POST (but not DELETE). Also, many body payloads require application/x-www-form-urlencoded MIME type. This quickly becomes unwieldy for complex payloads, particularly when arrays of objects are supplied. For example, creating a collection with a payload similar to

{
  "items": [
    {"type": "song", "id": "1"},
    {"type": "album", "id": "5"}
  ]
}

would require a pretty weird encoding that is - as far as I have checked - not well specified, or at least very convoluted.

I wonder if it makes sense to

• use POST for createCollection, PUT for updateCollection, DELETE for deleteCollection; not use GET
• use application/json in creation and update requests?

I see that you went with this approach in a recent change, so at least there is a precedent of not following the legacy Subsonic approaches.

[Tolriq]

New endpoints should use json it was added for that and move away from the limitation of original API.

[ygabuev]

I've modified the proposal a bit and also added the markdown pages, now it's application/json all the way. Would appreciate another look and more comments.

[lachlan-00]

collection should support everything which i think would be

• album
• artist
• bookmark bookarks are just entries so skip them
• genre
• internetradiostation
• playlist
• podcastepisode
• podcast
• share
• song
• user
• video

if you're going to enforce PUT and DELETE why add separate endpoints? it would only make sense if you were going to allow GET on all endpoints as well.

everything could just be on a collection endpoint if we are moving extensions to this style

[Tolriq]

There's no PUT and DELETE in the rest of the API there's no reason to introduce that now.

For collections, I do not see why it should contain bookmark or users or share.

[lachlan-00]

okay then take it out of the delete requirement for the endpoint https://github.com/opensubsonic/open-subsonic-api/pull/237/changes#diff-431be3340a9769c0f1c11bf62185826558cf6b1eb4de14bb6103e0f0db672539R14

bookmarks are just entries so they can be skipped but shares and users are unique enough to stay for me.

they're not as useful but it would be good to support everything possible

[Tolriq]

Shares can expire so does not make sense. Users are on most servers not visible from other users so also does not make sense.

[lachlan-00]

okay then don't add them

[ygabuev]

I've added the following types:

• genre
• internet radio station
• podcast episode
• podcast

Didn't add videos because they are not well defined in the API, would rather leave this as future work.

As a necessity, updated the collectionItemId type to support either id or name field because not all types support IDs, e.g. genre.

Also updated the HTTP method usage to only use GET and POST, in line with the rest of the API.