diff --git a/SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs b/SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs index 1651c441..7932d843 100644 --- a/SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs +++ b/SpotifyAPI.Web/Clients/Interfaces/IPlaylistsClient.cs @@ -5,33 +5,176 @@ namespace SpotifyAPI.Web { public interface IPlaylistsClient { + /// + /// Remove one or more items from a user’s playlist. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-remove-tracks-playlist + /// + /// Task RemoveItems(string playlistId, PlaylistRemoveItemsRequest request); + /// + /// Add one or more items to a user’s playlist. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-add-tracks-to-playlist + /// + /// Task AddItems(string playlistId, PlaylistAddItemsRequest request); + /// + /// Get full details of the items of a playlist owned by a Spotify user. + /// + /// The Spotify ID for the playlist. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlists-tracks + /// + /// Task>> GetItems(string playlistId); + + /// + /// Get full details of the items of a playlist owned by a Spotify user. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlists-tracks + /// + /// Task>> GetItems(string playlistId, PlaylistGetItemsRequest request); + /// + /// Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.) + /// + /// The user’s Spotify user ID. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-create-playlist + /// + /// Task Create(string userId, PlaylistCreateRequest request); + /// + /// Replace the image used to represent a specific playlist. + /// + /// The Spotify ID for the playlist. + /// Base64 encoded JPEG image data, maximum payload size is 256 KB. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-upload-custom-playlist-cover + /// + /// Task UploadCover(string playlistId, string base64JpgData); + + /// + /// Get the current image associated with a specific playlist. + /// + /// The Spotify ID for the playlist. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist-cover + /// + /// Task> GetCovers(string playlistId); + /// + /// Get a list of the playlists owned or followed by a Spotify user. + /// + /// The user’s Spotify user ID. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-list-users-playlists + /// + /// Task> GetUsers(string userId); + + /// + /// Get a list of the playlists owned or followed by a Spotify user. + /// + /// The user’s Spotify user ID. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-list-users-playlists + /// + /// Task> GetUsers(string userId, PlaylistGetUsersRequest request); + /// + /// Get a playlist owned by a Spotify user. + /// + /// The Spotify ID for the playlist. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist + /// + /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")] Task Get(string playlistId); + + /// + /// Get a playlist owned by a Spotify user. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-playlist + /// + /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Naming", "CA1716")] Task Get(string playlistId, PlaylistGetRequest request); + /// + /// Replace all the items in a playlist, overwriting its existing items. + /// This powerful request can be useful for replacing items, re-ordering existing items, or clearing the playlist. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-replace-playlists-tracks + /// + /// Task ReplaceItems(string playlistId, PlaylistReplaceItemsRequest request); + /// + /// Get a list of the playlists owned or followed by the current Spotify user. + /// + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-a-list-of-current-users-playlists + /// + /// Task> CurrentUsers(); + + /// + /// Get a list of the playlists owned or followed by the current Spotify user. + /// + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-get-a-list-of-current-users-playlists + /// + /// Task> CurrentUsers(PlaylistCurrentUsersRequest request); + /// + /// Change a playlist’s name and public/private state. (The user must, of course, own the playlist.) + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-change-playlist-details + /// + /// Task ChangeDetails(string playlistId, PlaylistChangeDetailsRequest request); + /// + /// Reorder an item or a group of items in a playlist. + /// + /// The Spotify ID for the playlist. + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-reorder-playlists-tracks + /// + /// Task ReorderItems(string playlistId, PlaylistReorderItemsRequest request); } } diff --git a/SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs b/SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs index d6471562..f479ff3e 100644 --- a/SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs +++ b/SpotifyAPI.Web/Clients/Interfaces/ISearchClient.cs @@ -4,6 +4,15 @@ namespace SpotifyAPI.Web { public interface ISearchClient { + /// + /// Get Spotify Catalog information about albums, artists, playlists, + /// tracks, shows or episodes that match a keyword string. + /// + /// The request-model which contains required and optional parameters. + /// + /// https://developer.spotify.com/documentation/web-api/reference-beta/#endpoint-search + /// + /// Task Item(SearchRequest request); } } diff --git a/SpotifyAPI.Web/Http/SimpleHTTPLogger.cs b/SpotifyAPI.Web/Http/SimpleConsoleHTTPLogger.cs similarity index 95% rename from SpotifyAPI.Web/Http/SimpleHTTPLogger.cs rename to SpotifyAPI.Web/Http/SimpleConsoleHTTPLogger.cs index d2487821..d202f70b 100644 --- a/SpotifyAPI.Web/Http/SimpleHTTPLogger.cs +++ b/SpotifyAPI.Web/Http/SimpleConsoleHTTPLogger.cs @@ -3,7 +3,7 @@ using System; namespace SpotifyAPI.Web.Http { - public class SimpleHTTPLogger : IHTTPLogger + public class SimpleConsoleHTTPLogger : IHTTPLogger { private const string OnRequestFormat = "\n{0} {1} [{2}] {3}"; diff --git a/SpotifyAPI.Web/Models/Request/PlaylistAddItemsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistAddItemsRequest.cs index 54a53ca5..ba6bca7b 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistAddItemsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistAddItemsRequest.cs @@ -4,6 +4,15 @@ namespace SpotifyAPI.Web { public class PlaylistAddItemsRequest : RequestParams { + /// + /// + /// + /// + /// A JSON array of the Spotify URIs to add. + /// For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", + /// "spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]} + /// A maximum of 100 items can be added in one request. + /// public PlaylistAddItemsRequest(IList uris) { Ensure.ArgumentNotNull(uris, nameof(uris)); @@ -11,9 +20,23 @@ namespace SpotifyAPI.Web Uris = uris; } + /// + /// A JSON array of the Spotify URIs to add. + /// For example: {"uris": ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", + /// "spotify:track:1301WleyT98MSxVHPZCA6M", "spotify:episode:512ojhOuo1ktJprKbVcKyQ"]} + /// A maximum of 100 items can be added in one request. + /// + /// [BodyParam("uris")] public IList Uris { get; } + /// + /// The position to insert the items, a zero-based index. + /// For example, to insert the items in the first position: position=0 ; + /// to insert the items in the third position: position=2. If omitted, the items will be appended to the playlist. + /// Items are added in the order they appear in the uris array. + /// + /// [BodyParam("position")] public int? Position { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistChangeDetailsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistChangeDetailsRequest.cs index ca84a05f..f4acc01d 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistChangeDetailsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistChangeDetailsRequest.cs @@ -2,15 +2,32 @@ namespace SpotifyAPI.Web { public class PlaylistChangeDetailsRequest : RequestParams { + /// + /// The new name for the playlist, for example "My New Playlist Title" + /// + /// [BodyParam("name")] public string? Name { get; set; } + /// + /// If true the playlist will be public, if false it will be private. + /// + /// [BodyParam("public")] public bool? Public { get; set; } + /// + /// If true , the playlist will become collaborative and other users will be able to modify the + /// playlist in their Spotify client. Note: You can only set collaborative to true on non-public playlists. + /// + /// [BodyParam("collaborative")] public bool? Collaborative { get; set; } + /// + /// Value for playlist description as displayed in Spotify Clients and in the Web API. + /// + /// [BodyParam("description")] public string? Description { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistCreateRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistCreateRequest.cs index 1a7c12dc..c4f879f3 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistCreateRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistCreateRequest.cs @@ -2,6 +2,12 @@ namespace SpotifyAPI.Web { public class PlaylistCreateRequest : RequestParams { + /// + /// + /// + /// The name for the new playlist, for example "Your Coolest Playlist" . + /// This name does not need to be unique; a user may have several playlists with the same name. + /// public PlaylistCreateRequest(string name) { Ensure.ArgumentNotNullOrEmptyString(name, nameof(name)); @@ -9,15 +15,36 @@ namespace SpotifyAPI.Web Name = name; } + /// + /// The name for the new playlist, for example "Your Coolest Playlist" . + /// This name does not need to be unique; a user may have several playlists with the same name. + /// + /// [BodyParam("name")] public string Name { get; } + /// + /// Defaults to true . If true the playlist will be public, if false it will be private. + /// To be able to create private playlists, the user must have granted the playlist-modify-private scope + /// + /// [BodyParam("public")] public bool? Public { get; set; } + /// + /// Defaults to false . If true the playlist will be collaborative. + /// Note that to create a collaborative playlist you must also set public to false . + /// To create collaborative playlists you must have + /// granted playlist-modify-private and playlist-modify-public scopes . + /// + /// [BodyParam("collaborative")] public bool? Collaborative { get; set; } + /// + /// value for playlist description as displayed in Spotify Clients and in the Web API. + /// + /// [BodyParam("description")] public string? Description { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistCurrentUsersRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistCurrentUsersRequest.cs index c2682274..da41e5cc 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistCurrentUsersRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistCurrentUsersRequest.cs @@ -2,9 +2,18 @@ namespace SpotifyAPI.Web { public class PlaylistCurrentUsersRequest : RequestParams { + /// + /// The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50. + /// + /// [QueryParam("limit")] public int? Limit { get; set; } + /// + /// The index of the first playlist to return. + /// Default: 0 (the first object). Maximum offset: 100.000. Use with limit to get the next set of playlists. + /// + /// [QueryParam("offset")] public int? Offset { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistGetItemsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistGetItemsRequest.cs index 96f23400..a175e032 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistGetItemsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistGetItemsRequest.cs @@ -5,6 +5,17 @@ namespace SpotifyAPI.Web { public class PlaylistGetItemsRequest : RequestParams { + /// + /// + /// + /// + /// A comma-separated list of item types that your client supports + /// besides the default track type. Valid types are: track and episode. + /// Note: This parameter was introduced to allow existing clients to maintain + /// their current behaviour and might be deprecated in the future. In addition to + /// providing this parameter, make sure that your client properly handles cases of new types in the + /// future by checking against the type field of each object. Defaults to ALL + /// public PlaylistGetItemsRequest(AdditionalTypes types = AdditionalTypes.All) { Ensure.ArgumentNotNull(types, nameof(types)); @@ -13,15 +24,44 @@ namespace SpotifyAPI.Web Fields = new List(); } + /// + /// Filters for the query: a comma-separated list of the fields to return. + /// If omitted, all fields are returned. For example, to get just the total number of items and the request limit: + /// fields=total,limit + /// A dot separator can be used to specify non-reoccurring fields, while parentheses can be used to specify + /// reoccurring fields within objects. For example, to get just the added date and user ID of the adder: + /// fields=items(added_at,added_by.id) + /// Use multiple parentheses to drill down into nested objects, for example: + /// fields=items(track(name,href,album(name,href))) + /// Fields can be excluded by prefixing them with an exclamation mark, for example: + /// fields=items.track.album(!external_urls,images) + /// + /// [QueryParam("fields")] public IList Fields { get; } + /// + /// The maximum number of items to return. Default: 100. Minimum: 1. Maximum: 100. + /// + /// [QueryParam("limit")] public int? Limit { get; set; } + /// + /// The index of the first item to return. Default: 0 (the first object). + /// + /// [QueryParam("offset")] public int? Offset { get; set; } + /// + /// An ISO 3166-1 alpha-2 country code or the string from_token. + /// Provide this parameter if you want to apply Track Relinking. For episodes, if a valid user access token is + /// specified in the request header, the country associated with the user account will take priority over this + /// parameter. Note: If neither market or user country are provided, + /// the episode is considered unavailable for the client. + /// + /// [QueryParam("market")] public string? Market { get; set; } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistGetUsersRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistGetUsersRequest.cs index 7be3c0b9..e553d538 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistGetUsersRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistGetUsersRequest.cs @@ -2,9 +2,18 @@ namespace SpotifyAPI.Web { public class PlaylistGetUsersRequest : RequestParams { + /// + /// The maximum number of playlists to return. Default: 20. Minimum: 1. Maximum: 50. + /// + /// [QueryParam("limit")] public int? Limit { get; set; } + /// + /// The index of the first playlist to return. Default: 0 (the first object). + /// Maximum offset: 100.000. Use with limit to get the next set of playlists. + /// + /// [QueryParam("offset")] public int? Offset { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistRemoveItemsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistRemoveItemsRequest.cs index 8008d558..8e68dccb 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistRemoveItemsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistRemoveItemsRequest.cs @@ -5,6 +5,15 @@ namespace SpotifyAPI.Web { public class PlaylistRemoveItemsRequest : RequestParams { + /// + /// + /// + /// + /// An array of objects containing Spotify URIs of the tracks or episodes to remove. + /// For example: { "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" }, + /// { "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }. + /// A maximum of 100 objects can be sent at once. + /// public PlaylistRemoveItemsRequest(IList tracks) { Ensure.ArgumentNotNullOrEmptyList(tracks, nameof(tracks)); @@ -12,9 +21,22 @@ namespace SpotifyAPI.Web Tracks = tracks; } + /// + /// An array of objects containing Spotify URIs of the tracks or episodes to remove. + /// For example: { "tracks": [{ "uri": "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" }, + /// { "uri": "spotify:track:1301WleyT98MSxVHPZCA6M" }] }. + /// A maximum of 100 objects can be sent at once. + /// + /// [BodyParam("tracks")] public IList Tracks { get; } + /// + /// The playlist’s snapshot ID against which you want to make the changes. + /// The API will validate that the specified items exist and in the specified positions and make the changes, + /// even if more recent changes have been made to the playlist. + /// + /// [BodyParam("snapshot_id")] public string? SnapshotId { get; set; } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistReorderItemsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistReorderItemsRequest.cs index b8179ef5..c0c5ebc9 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistReorderItemsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistReorderItemsRequest.cs @@ -2,21 +2,60 @@ namespace SpotifyAPI.Web { public class PlaylistReorderItemsRequest : RequestParams { + /// + /// + /// + /// + /// The position of the first item to be reordered. + /// + /// + /// The position where the items should be inserted. + /// To reorder the items to the end of the playlist, + /// simply set insert_before to the position after the last item. + /// Examples: To reorder the first item to the last position in a playlist with 10 items, + /// set range_start to 0, and insert_before to 10. To reorder the last item in a playlist + /// with 10 items to the start of the playlist, set range_start to 9, and insert_before to 0. + /// public PlaylistReorderItemsRequest(int rangeStart, int insertBefore) { RangeStart = rangeStart; InsertBefore = insertBefore; } + /// + /// The position of the first item to be reordered. + /// + /// [BodyParam("range_start")] public int RangeStart { get; set; } + /// + /// The position where the items should be inserted. + /// To reorder the items to the end of the playlist, + /// simply set insert_before to the position after the last item. + /// Examples: To reorder the first item to the last position in a playlist with 10 items, + /// set range_start to 0, and insert_before to 10. To reorder the last item in a playlist + /// with 10 items to the start of the playlist, set range_start to 9, and insert_before to 0. + /// + /// [BodyParam("insert_before")] public int InsertBefore { get; set; } + /// + /// The amount of items to be reordered. Defaults to 1 if not set. + /// The range of items to be reordered begins from the range_start position, and + /// includes the range_length subsequent items. + /// Example: To move the items at index 9-10 to the start of the playlist, + /// range_start is set to 9, and range_length is set to 2. + /// + /// [BodyParam("range_length")] public int? RangeLength { get; set; } + /// + /// The playlist’s snapshot ID against which you want to make the changes. + /// + /// [BodyParam("snapshot_id")] public string? SnapshotId { get; set; } } diff --git a/SpotifyAPI.Web/Models/Request/PlaylistReplaceItemsRequest.cs b/SpotifyAPI.Web/Models/Request/PlaylistReplaceItemsRequest.cs index 0ed7c15e..45458b90 100644 --- a/SpotifyAPI.Web/Models/Request/PlaylistReplaceItemsRequest.cs +++ b/SpotifyAPI.Web/Models/Request/PlaylistReplaceItemsRequest.cs @@ -4,6 +4,13 @@ namespace SpotifyAPI.Web { public class PlaylistReplaceItemsRequest : RequestParams { + /// + /// + /// + /// + /// A comma-separated list of Spotify URIs to set, can be track or episode URIs. + /// A maximum of 100 items can be set in one request. + /// public PlaylistReplaceItemsRequest(List uris) { Ensure.ArgumentNotNull(uris, nameof(uris)); @@ -11,6 +18,11 @@ namespace SpotifyAPI.Web Uris = uris; } + /// + /// A comma-separated list of Spotify URIs to set, can be track or episode URIs. + /// A maximum of 100 items can be set in one request. + /// + /// [BodyParam("uris")] public IList Uris { get; } } diff --git a/SpotifyAPI.Web/Models/Request/SearchRequest.cs b/SpotifyAPI.Web/Models/Request/SearchRequest.cs index fbdf75cf..5d645b8b 100644 --- a/SpotifyAPI.Web/Models/Request/SearchRequest.cs +++ b/SpotifyAPI.Web/Models/Request/SearchRequest.cs @@ -4,6 +4,20 @@ namespace SpotifyAPI.Web { public class SearchRequest : RequestParams { + /// + /// + /// + /// + /// A comma-separated list of item types to search across. + /// Valid types are: album , artist, playlist, track, show and episode. + /// Search results include hits from all the specified item types. + /// + /// + /// Search query keywords and optional field filters and operators. + /// + /// + /// https://developer.spotify.com/documentation/web-api/reference/search/search/ + /// public SearchRequest(Types type, string query) { Ensure.ArgumentNotNull(type, nameof(type)); @@ -13,21 +27,67 @@ namespace SpotifyAPI.Web Query = query; } + /// + /// A comma-separated list of item types to search across. + /// Valid types are: album , artist, playlist, track, show and episode. + /// Search results include hits from all the specified item types. + /// + /// [QueryParam("type")] public Types Type { get; set; } + /// + /// Search query keywords and optional field filters and operators. + /// + /// [QueryParam("q")] public string Query { get; set; } + /// + /// An ISO 3166-1 alpha-2 country code or the string from_token. + /// If a country code is specified, only content that is playable in that market is returned. + /// Note: + /// - Playlist results are not affected by the market parameter. + /// - If market is set to from_token, and a valid access token is + /// specified in the request header, only content playable in the country + /// associated with the user account, is returned. + /// - Users can view the country that is associated with their account in the + /// account settings. A user must grant access to the user-read-private scope + /// prior to when the access token is issued. + /// + /// [QueryParam("market")] public string? Market { get; set; } + /// + /// Maximum number of results to return. + /// Default: 20 + /// Minimum: 1 + /// Maximum: 50 + /// Note: The limit is applied within each type, not on the total response. + /// For example, if the limit value is 3 and the type is artist,album, + /// the response contains 3 artists and 3 albums. + /// + /// [QueryParam("limit")] public int? Limit { get; set; } + /// + /// The index of the first result to return. + /// Default: 0 (the first result). Maximum offset (including limit): 2,000. + /// Use with limit to get the next page of search results. + /// + /// [QueryParam("offset")] public int? Offset { get; set; } + /// + /// Possible values: audio + /// If include_external = audio is specified the response + /// will include any relevant audio content that is hosted externally. + /// By default external content is filtered out from responses. + /// + /// [QueryParam("include_external")] public IncludeExternals? IncludeExternal { get; set; }