shared/api/endpoints/
playlist.rs

1use crate::{
2    api::Method,
3    domain::{
4        playlist::{
5            ListLikedPath, ListLikedRequest, ListLikedResponse, PlaylistAdminDataUpdatePath,
6            PlaylistBrowsePath, PlaylistBrowseQuery, PlaylistBrowseResponse, PlaylistClonePath,
7            PlaylistCreatePath, PlaylistCreateRequest, PlaylistDeletePath, PlaylistGetDraftPath,
8            PlaylistGetLivePath, PlaylistId, PlaylistLikePath, PlaylistLikedPath,
9            PlaylistLikedResponse, PlaylistPublishPath, PlaylistResponse, PlaylistSearchPath,
10            PlaylistSearchQuery, PlaylistSearchResponse, PlaylistUnlikePath,
11            PlaylistUpdateAdminDataRequest, PlaylistUpdateDraftDataPath,
12            PlaylistUpdateDraftDataRequest, PlaylistViewPath,
13        },
14        CreateResponse,
15    },
16    error::{EmptyError, MetadataNotFound},
17};
18
19use super::ApiEndpoint;
20
21/// Create a Playlist and it's draft and live data copies.
22///
23/// * New Playlists are all set to `PrivacyLevel::Unlisted` by default
24///
25/// # Flow:
26/// 1. Create a Playlist and its two data copies with [`Create`]
27/// 2. Optionally update Playlist info such as privacy, author with [`Update`]
28/// 3. Make updates to draft data:
29///     a. Patch Playlist data through [`UpdateDraftData`]
30
31/// 4. Finalize draft changes by calling [`Publish`]
32///
33/// # Authorization
34/// * TokenUser
35/// * One of `Admin`, `AdminAsset`, or `ManageSelfAsset`
36pub struct Create;
37impl ApiEndpoint for Create {
38    type Req = PlaylistCreateRequest;
39    type Res = CreateResponse<PlaylistId>;
40    type Path = PlaylistCreatePath;
41    type Err = MetadataNotFound;
42    const METHOD: Method = Method::Post;
43}
44
45/// Get a Playlist's live data by ID.
46///
47/// # Authorization
48/// * Creator ID of Playlist
49/// * One of `Admin`, `AdminAsset`,, or `ManageSelfAsset` for owned Playlists
50///
51/// # Errors
52///
53pub struct GetLive;
54impl ApiEndpoint for GetLive {
55    type Req = ();
56    type Res = PlaylistResponse;
57    type Path = PlaylistGetLivePath;
58    type Err = EmptyError;
59    const METHOD: Method = Method::Get;
60}
61
62/// Get a Playlist's draft data by ID.
63///
64/// # Authorization
65/// * Creator ID of Playlist
66/// * One of `Admin`, `AdminAsset`,, or `ManageSelfAsset` for owned Playlists
67///
68/// # Errors
69/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
70///
71pub struct GetDraft;
72impl ApiEndpoint for GetDraft {
73    type Req = ();
74    type Res = PlaylistResponse;
75    type Path = PlaylistGetDraftPath;
76    type Err = EmptyError;
77    const METHOD: Method = Method::Get;
78}
79
80/// Update the draft data of a Playlist.
81///
82/// Note that a copy of the Playlist's draft or live data can not be fetched directly, but only as a part
83/// of one of the following routes:
84/// * [`GetLive`] fetches live copies
85/// * [`Search`]
86///
87/// See [`Playlist Data`](crate::domain::playlist::PlaylistData) for the over-the-wire representation.
88///
89/// # Authorization
90/// * One of `Admin`, `AdminAsset`, or `ManageSelfAsset` for owned Playlists
91pub struct UpdateDraftData;
92impl ApiEndpoint for UpdateDraftData {
93    type Req = PlaylistUpdateDraftDataRequest;
94    type Res = ();
95    type Path = PlaylistUpdateDraftDataPath;
96    type Err = MetadataNotFound;
97    const METHOD: Method = Method::Patch;
98}
99
100/// Publish a Playlist draft to live by copying over the Playlistdata.
101///
102/// # Authorization
103/// * Creator ID of Playlist
104/// * One of `Admin`, `AdminAsset`, or `ManageSelfAsset`
105pub struct Publish;
106impl ApiEndpoint for Publish {
107    type Req = ();
108    type Res = ();
109    type Path = PlaylistPublishPath;
110    type Err = EmptyError;
111    const METHOD: Method = Method::Put;
112}
113
114/// Browse Playlists. Returns the draft data copies in the response.
115///
116/// # Authorization
117/// * None
118pub struct Browse;
119impl ApiEndpoint for Browse {
120    type Req = PlaylistBrowseQuery;
121    type Res = PlaylistBrowseResponse;
122    type Path = PlaylistBrowsePath;
123    type Err = EmptyError;
124    const METHOD: Method = Method::Get;
125}
126
127/// Search for Playlists.
128///
129/// # Authorization
130/// * None
131pub struct Search;
132impl ApiEndpoint for Search {
133    type Req = PlaylistSearchQuery;
134    type Res = PlaylistSearchResponse;
135    type Path = PlaylistSearchPath;
136    type Err = EmptyError;
137    const METHOD: Method = Method::Get;
138}
139
140/// Delete a Playlist.
141///
142/// # Authorization
143/// * Creator ID of Playlist
144/// * One of `Admin`, `AdminAsset`, or `ManageSelfAsset` for owned Playlists
145pub struct Delete;
146impl ApiEndpoint for Delete {
147    type Req = ();
148    type Res = ();
149    type Path = PlaylistDeletePath;
150    type Err = EmptyError;
151    const METHOD: Method = Method::Delete;
152}
153
154/// Clone a Playlist. This clones both the draft and live.
155///
156/// # Authorization
157/// * One of `Admin`, `AdminAsset`, or `ManageSelfAsset`
158///
159/// # Errors
160/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
161/// * [`Forbidden`](http::StatusCode::FORBIDDEN) if the user does not have sufficient permission to perform the action.
162/// * ['NotFound'](http::StatusCode::NOT_FOUND) if the resource does not exist.
163/// * ['BadRequest'](http::StatusCode::BAD_REQUEST) if the request is malformed or the Playlist is a draft.
164pub struct Clone;
165impl ApiEndpoint for Clone {
166    type Path = PlaylistClonePath;
167    type Req = ();
168    type Res = CreateResponse<PlaylistId>;
169    type Err = EmptyError;
170    const METHOD: Method = Method::Post;
171}
172
173/// Like a Playlist
174///
175/// # Authorization
176/// * Admin, BasicAuth
177pub struct Like;
178impl ApiEndpoint for Like {
179    type Path = PlaylistLikePath;
180    type Req = ();
181    type Res = ();
182    type Err = EmptyError;
183    const METHOD: Method = Method::Put;
184}
185
186/// Unlike a Playlist
187///
188/// # Authorization
189/// * Admin, BasicAuth
190pub struct Unlike;
191impl ApiEndpoint for Unlike {
192    type Path = PlaylistUnlikePath;
193    type Req = ();
194    type Res = ();
195    type Err = EmptyError;
196    const METHOD: Method = Method::Delete;
197}
198
199/// List user's liked Playlists.
200pub struct ListLiked;
201impl ApiEndpoint for ListLiked {
202    type Req = ListLikedRequest;
203    type Res = ListLikedResponse;
204    type Path = ListLikedPath;
205    type Err = EmptyError;
206    const METHOD: Method = Method::Get;
207}
208
209/// Is a Playlist liked by a user
210///
211/// # Authorization
212/// * Admin, BasicAuth
213pub struct Liked;
214impl ApiEndpoint for Liked {
215    type Path = PlaylistLikedPath;
216    type Req = ();
217    type Res = PlaylistLikedResponse;
218    type Err = EmptyError;
219    const METHOD: Method = Method::Get;
220}
221
222/// View a Playlist
223///
224/// # Authorization
225/// * None
226pub struct View;
227impl ApiEndpoint for View {
228    type Path = PlaylistViewPath;
229    type Req = ();
230    type Res = ();
231    type Err = EmptyError;
232    const METHOD: Method = Method::Put;
233}
234
235/// Update an admin data for a JIG.
236///
237/// # Authorization
238///
239/// * Standard + [`UserScope::AdminAsset`](crate::domain::user::UserScope)
240///
241/// # Errors
242///
243/// * [`Unauthorized`](http::StatusCode::UNAUTHORIZED) if authorization is not valid.
244/// * [`Forbidden`](http::StatusCode::FORBIDDEN) if the user does not have sufficient permission to perform the action.
245/// * [`BadRequest`](http::StatusCode::BAD_REQUEST) if the request is missing/invalid.
246pub struct PlaylistAdminDataUpdate;
247impl ApiEndpoint for PlaylistAdminDataUpdate {
248    type Path = PlaylistAdminDataUpdatePath;
249    type Req = PlaylistUpdateAdminDataRequest;
250    type Res = ();
251    type Err = EmptyError;
252    const METHOD: Method = Method::Patch;
253}