qobuz_api_rust/api/content/
playlists.rs

1use crate::{
2    api::service::QobuzApiService,
3    errors::QobuzApiError::{self},
4    models::{Playlist, SearchResult},
5};
6
7impl QobuzApiService {
8    /// Retrieves a specific playlist by its ID from the Qobuz API.
9    ///
10    /// This method fetches detailed information about a single playlist, including its metadata,
11    /// tracks, and other associated information. The playlist ID uniquely identifies the playlist
12    /// in the Qobuz system.
13    ///
14    /// # Arguments
15    ///
16    /// * `playlist_id` - The unique identifier of the playlist to retrieve
17    /// * `with_auth` - Optional boolean to execute request with user authentication token.
18    ///   If `None` or `Some(false)`, the request is made without authentication.
19    ///   If `Some(true)`, the request uses the stored authentication token if available.
20    /// * `extra` - Optional string specifying additional information to include in the response.
21    ///   This can be used to request additional metadata or related content.
22    /// * `limit` - Optional integer specifying the maximum number of extra results to return.
23    ///   Defaults to 25 if not specified.
24    /// * `offset` - Optional integer specifying the offset of the first extra result to return.
25    ///   Defaults to 0 if not specified.
26    ///
27    /// # Examples
28    ///
29    /// ```rust,no_run
30    /// # use qobuz_api_rust::{QobuzApiService, QobuzApiError};
31    /// # async fn example() -> Result<(), QobuzApiError> {
32    /// let service = QobuzApiService::new().await?;
33    ///
34    /// // Get a playlist by ID without additional parameters
35    /// let playlist = service.get_playlist("12345", None, None, None, None).await?;
36    /// println!("Playlist name: {:?}", playlist.name);
37    ///
38    /// // Get a playlist with authentication and extra data
39    /// let playlist = service.get_playlist(
40    ///     "12345",
41    ///     Some(true),
42    ///     Some("tracks,owner"),
43    ///     Some(50),
44    ///     Some(0)
45    /// ).await?;
46    /// # Ok(())
47    /// # }
48    /// ```
49    ///
50    /// # Returns
51    ///
52    /// * `Ok(Playlist)` - Successfully retrieved playlist with all available information
53    /// * `Err(QobuzApiError)` - If the API request fails due to network issues, invalid parameters,
54    ///   authentication problems, or if the playlist doesn't exist
55    pub async fn get_playlist(
56        &self,
57        playlist_id: &str,
58        with_auth: Option<bool>,
59        extra: Option<&str>,
60        limit: Option<i32>,
61        offset: Option<i32>,
62    ) -> Result<Playlist, QobuzApiError> {
63        let mut params = vec![("playlist_id".to_string(), playlist_id.to_string())];
64
65        if let Some(extra_val) = extra {
66            params.push(("extra".to_string(), extra_val.to_string()));
67        }
68
69        params.push(("limit".to_string(), limit.unwrap_or(25).to_string()));
70        params.push(("offset".to_string(), offset.unwrap_or(0).to_string()));
71
72        let _use_auth = with_auth.unwrap_or(false);
73
74        self.get("/playlist/get", &params).await
75    }
76
77    /// Searches for playlists using a text query through the Qobuz API.
78    ///
79    /// This method allows you to search for playlists based on a text query, which can match
80    /// playlist names, descriptions, or other relevant metadata. The results are returned as
81    /// a paginated list of playlists that match the search criteria.
82    ///
83    /// # Arguments
84    ///
85    /// * `query` - The search query string to match against playlist names, descriptions, etc.
86    /// * `limit` - Optional integer specifying the maximum number of results to return.
87    ///   Defaults to 50 if not specified. Maximum values may be enforced by the API.
88    /// * `offset` - Optional integer specifying the offset of the first result to return,
89    ///   used for pagination. Defaults to 0 if not specified.
90    /// * `with_auth` - Optional boolean to execute search with user authentication token.
91    ///   If `None` or `Some(false)`, the search is made without authentication.
92    ///   If `Some(true)`, the search uses the stored authentication token if available.
93    ///
94    /// # Examples
95    ///
96    /// ```rust,no_run
97    /// # use qobuz_api_rust::{QobuzApiService, QobuzApiError};
98    /// # async fn example() -> Result<(), QobuzApiError> {
99    /// let service = QobuzApiService::new().await?;
100    ///
101    /// // Search for playlists containing "chill" without authentication
102    /// let results = service.search_playlists("chill", None, None, None).await?;
103    /// if let Some(playlists) = &results.playlists {
104    ///     println!("Found {} playlists", playlists.total.unwrap_or(0));
105    /// }
106    ///
107    /// // Search with pagination and authentication
108    /// let results = service.search_playlists("jazz", Some(20), Some(40), Some(true)).await?;
109    /// # Ok(())
110    /// # }
111    /// ```
112    ///
113    /// # Returns
114    ///
115    /// * `Ok(SearchResult)` - Successfully retrieved search results containing matching playlists
116    ///   and metadata about the search (total count, pagination info, etc.)
117    /// * `Err(QobuzApiError)` - If the API request fails due to network issues, invalid parameters,
118    ///   authentication problems, or other API-related errors
119    pub async fn search_playlists(
120        &self,
121        query: &str,
122        limit: Option<i32>,
123        offset: Option<i32>,
124        with_auth: Option<bool>,
125    ) -> Result<SearchResult, QobuzApiError> {
126        let params = vec![
127            ("query".to_string(), query.to_string()),
128            ("limit".to_string(), limit.unwrap_or(50).to_string()),
129            ("offset".to_string(), offset.unwrap_or(0).to_string()),
130        ];
131
132        let _use_auth = with_auth.unwrap_or(false);
133
134        self.get("/playlist/search", &params).await
135    }
136}
qobuz_api_rust/api/content/playlists.rs

qobuz_api_rust/api/content/
playlists.rs
