Skip to content

Commit 7445d3c

Browse files
JohnnyCrazyJohnnyCrazy
committed
📘 More docs! #451 
1 parent 4c38f95 commit 7445d3c

13 files changed

Lines changed: 411 additions & 1 deletion

‎SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,33 +5,176 @@ namespace SpotifyAPI.Web
55
{
66
public interface IPlaylistsClient
77
{
8+
/// <summary>
9+
/// Remove one or more items from a user’s playlist.
10+
/// </summary>
11+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
12+
/// <param name="request">The request-model which contains required and optional parameters.</param>
13+
/// <remarks>
14+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-remove-tracks-playlist
15+
/// </remarks>
16+
/// <returns></returns>
817
Task<SnapshotResponse> RemoveItems(string playlistId, PlaylistRemoveItemsRequest request);
918

19+
/// <summary>
20+
/// Add one or more items to a user’s playlist.
21+
/// </summary>
22+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
23+
/// <param name="request">The request-model which contains required and optional parameters.</param>
24+
/// <remarks>
25+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-add-tracks-to-playlist
26+
/// </remarks>
27+
/// <returns></returns>
1028
Task<SnapshotResponse> AddItems(string playlistId, PlaylistAddItemsRequest request);
1129

30+
/// <summary>
31+
/// Get full details of the items of a playlist owned by a Spotify user.
32+
/// </summary>
33+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
34+
/// <remarks>
35+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlists-tracks
36+
/// </remarks>
37+
/// <returns></returns>
1238
Task<Paging<PlaylistTrack<IPlayableItem>>> GetItems(string playlistId);
39+
40+
/// <summary>
41+
/// Get full details of the items of a playlist owned by a Spotify user.
42+
/// </summary>
43+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
44+
/// <param name="request">The request-model which contains required and optional parameters.</param>
45+
/// <remarks>
46+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlists-tracks
47+
/// </remarks>
48+
/// <returns></returns>
1349
Task<Paging<PlaylistTrack<IPlayableItem>>> GetItems(string playlistId, PlaylistGetItemsRequest request);
1450

51+
/// <summary>
52+
/// Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
53+
/// </summary>
54+
/// <param name="userId">The user’s Spotify user ID.</param>
55+
/// <param name="request">The request-model which contains required and optional parameters.</param>
56+
/// <remarks>
57+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-create-playlist
58+
/// </remarks>
59+
/// <returns></returns>
1560
Task<FullPlaylist> Create(string userId, PlaylistCreateRequest request);
1661

62+
/// <summary>
63+
/// Replace the image used to represent a specific playlist.
64+
/// </summary>
65+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
66+
/// <param name="base64JpgData">Base64 encoded JPEG image data, maximum payload size is 256 KB.</param>
67+
/// <remarks>
68+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-upload-custom-playlist-cover
69+
/// </remarks>
70+
/// <returns></returns>
1771
Task<bool> UploadCover(string playlistId, string base64JpgData);
72+
73+
/// <summary>
74+
/// Get the current image associated with a specific playlist.
75+
/// </summary>
76+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
77+
/// <remarks>
78+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist-cover
79+
/// </remarks>
80+
/// <returns></returns>
1881
Task<List<Image>> GetCovers(string playlistId);
1982

83+
/// <summary>
84+
/// Get a list of the playlists owned or followed by a Spotify user.
85+
/// </summary>
86+
/// <param name="userId">The user’s Spotify user ID.</param>
87+
/// <remarks>
88+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-list-users-playlists
89+
/// </remarks>
90+
/// <returns></returns>
2091
Task<Paging<SimplePlaylist>> GetUsers(string userId);
92+
93+
/// <summary>
94+
/// Get a list of the playlists owned or followed by a Spotify user.
95+
/// </summary>
96+
/// <param name="userId">The user’s Spotify user ID.</param>
97+
/// <param name="request">The request-model which contains required and optional parameters.</param>
98+
/// <remarks>
99+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-list-users-playlists
100+
/// </remarks>
101+
/// <returns></returns>
21102
Task<Paging<SimplePlaylist>> GetUsers(string userId, PlaylistGetUsersRequest request);
22103

104+
/// <summary>
105+
/// Get a playlist owned by a Spotify user.
106+
/// </summary>
107+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
108+
/// <remarks>
109+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist
110+
/// </remarks>
111+
/// <returns></returns>
23112
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")]
24113
Task<FullPlaylist> Get(string playlistId);
114+
115+
/// <summary>
116+
/// Get a playlist owned by a Spotify user.
117+
/// </summary>
118+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
119+
/// <param name="request">The request-model which contains required and optional parameters.</param>
120+
/// <remarks>
121+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist
122+
/// </remarks>
123+
/// <returns></returns>
25124
[System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")]
26125
Task<FullPlaylist> Get(string playlistId, PlaylistGetRequest request);
27126

127+
/// <summary>
128+
/// Replace all the items in a playlist, overwriting its existing items.
129+
/// This powerful request can be useful for replacing items, re-ordering existing items, or clearing the playlist.
130+
/// </summary>
131+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
132+
/// <param name="request">The request-model which contains required and optional parameters.</param>
133+
/// <remarks>
134+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-replace-playlists-tracks
135+
/// </remarks>
136+
/// <returns></returns>
28137
Task<bool> ReplaceItems(string playlistId, PlaylistReplaceItemsRequest request);
29138

139+
/// <summary>
140+
/// Get a list of the playlists owned or followed by the current Spotify user.
141+
/// </summary>
142+
/// <remarks>
143+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-a-list-of-current-users-playlists
144+
/// </remarks>
145+
/// <returns></returns>
30146
Task<Paging<SimplePlaylist>> CurrentUsers();
147+
148+
/// <summary>
149+
/// Get a list of the playlists owned or followed by the current Spotify user.
150+
/// </summary>
151+
/// <param name="request">The request-model which contains required and optional parameters.</param>
152+
/// <remarks>
153+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-a-list-of-current-users-playlists
154+
/// </remarks>
155+
/// <returns></returns>
31156
Task<Paging<SimplePlaylist>> CurrentUsers(PlaylistCurrentUsersRequest request);
32157

158+
/// <summary>
159+
/// Change a playlist’s name and public/private state. (The user must, of course, own the playlist.)
160+
/// </summary>
161+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
162+
/// <param name="request">The request-model which contains required and optional parameters.</param>
163+
/// <remarks>
164+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-change-playlist-details
165+
/// </remarks>
166+
/// <returns></returns>
33167
Task<bool> ChangeDetails(string playlistId, PlaylistChangeDetailsRequest request);
34168

169+
/// <summary>
170+
/// Reorder an item or a group of items in a playlist.
171+
/// </summary>
172+
/// <param name="playlistId">The Spotify ID for the playlist.</param>
173+
/// <param name="request">The request-model which contains required and optional parameters.</param>
174+
/// <remarks>
175+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-reorder-playlists-tracks
176+
/// </remarks>
177+
/// <returns></returns>
35178
Task<SnapshotResponse> ReorderItems(string playlistId, PlaylistReorderItemsRequest request);
36179
}
37180
}

‎SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,15 @@ namespace SpotifyAPI.Web
44
{
55
public interface ISearchClient
66
{
7+
/// <summary>
8+
/// Get Spotify Catalog information about albums, artists, playlists,
9+
/// tracks, shows or episodes that match a keyword string.
10+
/// </summary>
11+
/// <param name="request">The request-model which contains required and optional parameters.</param>
12+
/// <remarks>
13+
/// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-search
14+
/// </remarks>
15+
/// <returns></returns>
716
Task<SearchResponse> Item(SearchRequest request);
817
}
918
}

SpotifyAPI.Web/Http/SimpleHTTPLogger.cs renamed to SpotifyAPI.Web/Http/SimpleConsoleHTTPLogger.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
namespace SpotifyAPI.Web.Http
55
{
6-
public class SimpleHTTPLogger : IHTTPLogger
6+
public class SimpleConsoleHTTPLogger : IHTTPLogger
77
{
88
private const string OnRequestFormat = "\n{0} {1} [{2}] {3}";
99

‎SpotifyAPI.Web/Models/Request/PlaylistAddItemsRequest.cs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,39 @@ namespace SpotifyAPI.Web
44
{
55
public class PlaylistAddItemsRequest : RequestParams
66
{
7+
/// <summary>
8+
///
9+
/// </summary>
10+
/// <param name="uris">
11+
/// A JSON array of the Spotify URIs to add.
12+
/// For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
13+
/// "spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}
14+
/// A maximum of 100 items can be added in one request.
15+
/// </param>
716
public PlaylistAddItemsRequest(IList<string> uris)
817
{
918
Ensure.ArgumentNotNull(uris, nameof(uris));
1019

1120
Uris = uris;
1221
}
1322

23+
/// <summary>
24+
/// A JSON array of the Spotify URIs to add.
25+
/// For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh",
26+
/// "spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]}
27+
/// A maximum of 100 items can be added in one request.
28+
/// </summary>
29+
/// <value></value>
1430
[BodyParam("uris")]
1531
public IList<string> Uris { get; }
1632

33+
/// <summary>
34+
/// The position to insert the items, a zero-based index.
35+
/// For example, to insert the items in the first position: position=0 ;
36+
/// to insert the items in the third position: position=2. If omitted, the items will be appended to the playlist.
37+
/// Items are added in the order they appear in the uris array.
38+
/// </summary>
39+
/// <value></value>
1740
[BodyParam("position")]
1841
public int? Position { get; set; }
1942
}

‎SpotifyAPI.Web/Models/Request/PlaylistChangeDetailsRequest.cs‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,32 @@ namespace SpotifyAPI.Web
22
{
33
public class PlaylistChangeDetailsRequest : RequestParams
44
{
5+
/// <summary>
6+
/// The new name for the playlist, for example "My New Playlist Title"
7+
/// </summary>
8+
/// <value></value>
59
[BodyParam("name")]
610
public string? Name { get; set; }
711

12+
/// <summary>
13+
/// If true the playlist will be public, if false it will be private.
14+
/// </summary>
15+
/// <value></value>
816
[BodyParam("public")]
917
public bool? Public { get; set; }
1018

19+
/// <summary>
20+
/// If true , the playlist will become collaborative and other users will be able to modify the
21+
/// playlist in their Spotify client. Note: You can only set collaborative to true on non-public playlists.
22+
/// </summary>
23+
/// <value></value>
1124
[BodyParam("collaborative")]
1225
public bool? Collaborative { get; set; }
1326

27+
/// <summary>
28+
/// Value for playlist description as displayed in Spotify Clients and in the Web API.
29+
/// </summary>
30+
/// <value></value>
1431
[BodyParam("description")]
1532
public string? Description { get; set; }
1633
}

‎SpotifyAPI.Web/Models/Request/PlaylistCreateRequest.cs‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,22 +2,49 @@ namespace SpotifyAPI.Web
22
{
33
public class PlaylistCreateRequest : RequestParams
44
{
5+
/// <summary>
6+
/// </summary>
7+
/// <param name="name">
8+
/// The name for the new playlist, for example "Your Coolest Playlist" .
9+
/// This name does not need to be unique; a user may have several playlists with the same name.
10+
/// </param>
511
public PlaylistCreateRequest(string name)
612
{
713
Ensure.ArgumentNotNullOrEmptyString(name, nameof(name));
814

915
Name = name;
1016
}
1117

18+
/// <summary>
19+
/// The name for the new playlist, for example "Your Coolest Playlist" .
20+
/// This name does not need to be unique; a user may have several playlists with the same name.
21+
/// </summary>
22+
/// <value></value>
1223
[BodyParam("name")]
1324
public string Name { get; }
1425

26+
/// <summary>
27+
/// Defaults to true . If true the playlist will be public, if false it will be private.
28+
/// To be able to create private playlists, the user must have granted the playlist-modify-private scope
29+
/// </summary>
30+
/// <value></value>
1531
[BodyParam("public")]
1632
public bool? Public { get; set; }
1733

34+
/// <summary>
35+
/// Defaults to false . If true the playlist will be collaborative.
36+
/// Note that to create a collaborative playlist you must also set public to false .
37+
/// To create collaborative playlists you must have
38+
/// granted playlist-modify-private and playlist-modify-public scopes .
39+
/// </summary>
40+
/// <value></value>
1841
[BodyParam("collaborative")]
1942
public bool? Collaborative { get; set; }
2043

44+
/// <summary>
45+
/// value for playlist description as displayed in Spotify Clients and in the Web API.
46+
/// </summary>
47+
/// <value></value>
2148
[BodyParam("description")]
2249
public string? Description { get; set; }
2350
}

‎SpotifyAPI.Web/Models/Request/PlaylistCurrentUsersRequest.cs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,18 @@ namespace SpotifyAPI.Web
22
{
33
public class PlaylistCurrentUsersRequest : RequestParams
44
{
5+
/// <summary>
6+
/// The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50.
7+
/// </summary>
8+
/// <value></value>
59
[QueryParam("limit")]
610
public int? Limit { get; set; }
711

12+
/// <summary>
13+
/// The index of the first playlist to return.
14+
/// Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists.
15+
/// </summary>
16+
/// <value></value>
817
[QueryParam("offset")]
918
public int? Offset { get; set; }
1019
}

0 commit comments

Comments
 (0)