Skip to content

Commit dd5e95a

Browse files
ygabuevygabuev
committed
Add collections
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.
1 parent 899c511 commit dd5e95a

16 files changed

Lines changed: 959 additions & 0 deletions

‎openapi/endpoints/createCollection.json‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
{
2+
"get": {
3+
"summary": "Creates (or updates) a collection.",
4+
"description": "Creates (or updates) a collection.",
5+
"operationId": "createCollection",
6+
"tags": [
7+
"Collections"
8+
],
9+
"parameters": [
10+
{
11+
"name": "collectionId",
12+
"in": "query",
13+
"description": "The collection ID. Required if updating an existing collection.",
14+
"required": false,
15+
"schema": {
16+
"type": "string"
17+
}
18+
},
19+
{
20+
"name": "name",
21+
"in": "query",
22+
"description": "The human-readable name of the collection. Required if creating a new collection.",
23+
"required": false,
24+
"schema": {
25+
"type": "string"
26+
}
27+
},
28+
{
29+
"name": "songId",
30+
"in": "query",
31+
"description": "ID of a song in the collection. Use one `songId` parameter for each song in the collection.",
32+
"explode": true,
33+
"style": "form",
34+
"schema": {
35+
"type": "array",
36+
"items": {
37+
"type": "string"
38+
}
39+
}
40+
},
41+
{
42+
"name": "albumId",
43+
"in": "query",
44+
"description": "ID of an album in the collection. Use one `albumId` parameter for each album in the collection.",
45+
"explode": true,
46+
"style": "form",
47+
"schema": {
48+
"type": "array",
49+
"items": {
50+
"type": "string"
51+
}
52+
}
53+
},
54+
{
55+
"name": "artistId",
56+
"in": "query",
57+
"description": "ID of an artist in the collection. Use one `artistId` parameter for each artist in the collection.",
58+
"explode": true,
59+
"style": "form",
60+
"schema": {
61+
"type": "array",
62+
"items": {
63+
"type": "string"
64+
}
65+
}
66+
},
67+
{
68+
"name": "playlistId",
69+
"in": "query",
70+
"description": "ID of an playlist in the collection. Use one `playlistId` parameter for each playlist in the collection.",
71+
"explode": true,
72+
"style": "form",
73+
"schema": {
74+
"type": "array",
75+
"items": {
76+
"type": "string"
77+
}
78+
}
79+
}
80+
],
81+
"responses": {
82+
"200": {
83+
"description": "Successful or failed response",
84+
"content": {
85+
"application/json": {
86+
"schema": {
87+
"$ref": "./createCollection/CreateCollectionResponse.json"
88+
}
89+
}
90+
}
91+
}
92+
},
93+
"externalDocs": {
94+
"description": "createCollection",
95+
"url": "https://opensubsonic.netlify.app/docs/endpoints/createcollection/"
96+
}
97+
},
98+
"post": {
99+
"summary": "Creates (or updates) a collection.",
100+
"description": "Creates (or updates) a collection.\n\nRequires OpenSubsonic extension name `formPost` (As returned by `getOpenSubsonicExtensions`)",
101+
"operationId": "postCreateCollection",
102+
"tags": [
103+
"Collections"
104+
],
105+
"requestBody": {
106+
"required": true,
107+
"content": {
108+
"application/x-www-form-urlencoded": {
109+
"schema": {
110+
"type": "object",
111+
"properties": {
112+
"collectionId": {
113+
"type": "string",
114+
"description": "The collection ID. Required if updating an existing collection."
115+
},
116+
"name": {
117+
"type": "string",
118+
"description": "The human-readable name of the collection. Required if creating a new collection."
119+
},
120+
"songId": {
121+
"type": "array",
122+
"items": {
123+
"type": "string"
124+
},
125+
"description": "ID of a song in the collection. Use one `songId` parameter for each song in the collection."
126+
},
127+
"albumId": {
128+
"type": "array",
129+
"items": {
130+
"type": "string"
131+
},
132+
"description": "ID of a album in the collection. Use one `albumId` parameter for each album in the collection."
133+
},
134+
"artistId": {
135+
"type": "array",
136+
"items": {
137+
"type": "string"
138+
},
139+
"description": "ID of a artist in the collection. Use one `artistId` parameter for each artist in the collection."
140+
},
141+
"playlistId": {
142+
"type": "array",
143+
"items": {
144+
"type": "string"
145+
},
146+
"description": "ID of a playlist in the collection. Use one `playlistId` parameter for each playlist in the collection."
147+
}
148+
}
149+
}
150+
}
151+
}
152+
},
153+
"parameters": [
154+
155+
],
156+
"responses": {
157+
"200": {
158+
"description": "Successful or failed response",
159+
"content": {
160+
"application/json": {
161+
"schema": {
162+
"$ref": "./createCollection/CreateCollectionResponse.json"
163+
}
164+
}
165+
}
166+
},
167+
"405": {
168+
"$ref": "../responses/HTTPFormPostNotSupported.json"
169+
}
170+
},
171+
"externalDocs": {
172+
"description": "createCollection",
173+
"url": "https://opensubsonic.netlify.app/docs/endpoints/createcollection/"
174+
}
175+
}
176+
}

‎openapi/endpoints/createCollection/CreateCollectionResponse.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"type": "object",
3+
"description": "A subsonic-response element with a nested collection element on success.",
4+
"properties": {
5+
"subsonic-response": {
6+
"oneOf": [
7+
{
8+
"$ref": "./CreateCollectionSuccessResponse.json"
9+
},
10+
{
11+
"$ref": "../../schemas/SubsonicResponse/SubsonicFailureResponse.json"
12+
}
13+
]
14+
}
15+
},
16+
"externalDocs": {
17+
"description": "CreateCollectionResponse",
18+
"url": "https://opensubsonic.netlify.app/docs/endpoints/createcollection/"
19+
}
20+
}

‎openapi/endpoints/createCollection/CreateCollectionSuccessResponse.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"allOf": [
3+
{
4+
"$ref": "../../schemas/SubsonicResponse/SubsonicSuccessResponse.json"
5+
},
6+
{
7+
"type": "object",
8+
"properties": {
9+
"collection": {
10+
"$ref": "../../schemas/CollectionWithItems.json"
11+
}
12+
},
13+
"required": [
14+
"collection"
15+
]
16+
}
17+
]
18+
}

‎openapi/endpoints/deleteCollection.json‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
{
2+
"get": {
3+
"summary": "Deletes a saved collection.",
4+
"description": "Deletes a saved collection.",
5+
"operationId": "deleteCollection",
6+
"tags": [
7+
"Collections"
8+
],
9+
"parameters": [
10+
{
11+
"name": "id",
12+
"in": "query",
13+
"description": "ID of the collection to delete, as obtained by `getCollections`.",
14+
"required": true,
15+
"schema": {
16+
"type": "string"
17+
}
18+
}
19+
],
20+
"responses": {
21+
"200": {
22+
"$ref": "../responses/EmptySubsonicResponse.json"
23+
}
24+
},
25+
"externalDocs": {
26+
"description": "deleteCollection",
27+
"url": "https://opensubsonic.netlify.app/docs/endpoints/deletecollection/"
28+
}
29+
},
30+
"post": {
31+
"summary": "Deletes a saved collection.",
32+
"description": "Deletes a saved collection.\n\nRequires OpenSubsonic extension name `formPost` (As returned by `getOpenSubsonicExtensions`)",
33+
"operationId": "postDeleteCollection",
34+
"tags": [
35+
"Collections"
36+
],
37+
"requestBody": {
38+
"required": true,
39+
"content": {
40+
"application/x-www-form-urlencoded": {
41+
"schema": {
42+
"type": "object",
43+
"properties": {
44+
"id": {
45+
"type": "string",
46+
"description": "ID of the collection to delete, as obtained by `getCollections`."
47+
}
48+
},
49+
"required": [
50+
"id"
51+
]
52+
}
53+
}
54+
}
55+
},
56+
"parameters": [
57+
58+
],
59+
"responses": {
60+
"200": {
61+
"$ref": "../responses/EmptySubsonicResponse.json"
62+
},
63+
"405": {
64+
"$ref": "../responses/HTTPFormPostNotSupported.json"
65+
}
66+
},
67+
"externalDocs": {
68+
"description": "deleteCollection",
69+
"url": "https://opensubsonic.netlify.app/docs/endpoints/deletecollection/"
70+
}
71+
}
72+
}

‎openapi/endpoints/getCollection.json‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
{
2+
"get": {
3+
"summary": "Returns a collection.",
4+
"description": "Returns a collection.",
5+
"operationId": "getCollection",
6+
"tags": [
7+
"Collections"
8+
],
9+
"parameters": [
10+
{
11+
"name": "id",
12+
"in": "query",
13+
"description": "ID of the collection to return, as obtained by `getCollections`.",
14+
"required": true,
15+
"schema": {
16+
"type": "string"
17+
}
18+
}
19+
],
20+
"responses": {
21+
"200": {
22+
"description": "Successful or failed response",
23+
"content": {
24+
"application/json": {
25+
"schema": {
26+
"$ref": "./getCollection/GetCollectionResponse.json"
27+
}
28+
}
29+
}
30+
}
31+
},
32+
"externalDocs": {
33+
"description": "getCollection",
34+
"url": "https://opensubsonic.netlify.app/docs/endpoints/getcollection/"
35+
}
36+
},
37+
"post": {
38+
"summary": "Returns a collection.",
39+
"description": "Returns a collection.\n\nRequires OpenSubsonic extension name `formPost` (As returned by `getOpenSubsonicExtensions`)",
40+
"operationId": "postGetCollection",
41+
"tags": [
42+
"Collections"
43+
],
44+
"requestBody": {
45+
"required": true,
46+
"content": {
47+
"application/x-www-form-urlencoded": {
48+
"schema": {
49+
"type": "object",
50+
"properties": {
51+
"id": {
52+
"type": "string",
53+
"description": "ID of the collection to return, as obtained by `getCollections`."
54+
}
55+
},
56+
"required": [
57+
"id"
58+
]
59+
}
60+
}
61+
}
62+
},
63+
"parameters": [
64+
],
65+
"responses": {
66+
"200": {
67+
"description": "Successful or failed response",
68+
"content": {
69+
"application/json": {
70+
"schema": {
71+
"$ref": "./getCollection/GetCollectionResponse.json"
72+
}
73+
}
74+
}
75+
},
76+
"405": {
77+
"$ref": "../responses/HTTPFormPostNotSupported.json"
78+
}
79+
},
80+
"externalDocs": {
81+
"description": "getCollection",
82+
"url": "https://opensubsonic.netlify.app/docs/endpoints/getcollection/"
83+
}
84+
}
85+
}

‎openapi/endpoints/getCollection/GetCollectionResponse.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"type": "object",
3+
"description": "A subsonic-response element with a nested collection element on success.",
4+
"properties": {
5+
"subsonic-response": {
6+
"oneOf": [
7+
{
8+
"$ref": "./GetCollectionSuccessResponse.json"
9+
},
10+
{
11+
"$ref": "../../schemas/SubsonicResponse/SubsonicFailureResponse.json"
12+
}
13+
]
14+
}
15+
},
16+
"externalDocs": {
17+
"description": "GetCollectionResponse",
18+
"url": "https://opensubsonic.netlify.app/docs/endpoints/getcollection/"
19+
}
20+
}

0 commit comments

Comments
 (0)