Expand description
RSpotify is a wrapper for the Spotify Web API, inspired by spotipy. It includes support for all the authorization flows, and helper methods for all available endpoints.
§Configuration
§HTTP Client
By default, RSpotify uses the reqwest asynchronous HTTP client with its default TLS, but you can customize both the HTTP client and the TLS with the following features:
- reqwest: enabling
client-reqwest
, TLS available:reqwest-default-tls
(reqwest’s default)reqwest-rustls-tls
reqwest-native-tls
reqwest-native-tls-vendored
- ureq: enabling
client-ureq
, TLS available:ureq-rustls-tls
(ureq’s default)ureq-rustls-tls-native-certs
(rustls
with OS root certificates)
If you want to use a different client or TLS than the default ones, you’ll
have to disable the default features and enable whichever you want. For
example, this would compile RSpotify with reqwest
and the native TLS:
[dependencies]
rspotify = {
version = "...",
default-features = false,
features = ["client-reqwest", "reqwest-native-tls"]
}
maybe_async
internally enables RSpotify to use both synchronous and
asynchronous HTTP clients. You can also use ureq
, a synchronous client,
like so:
[dependencies]
rspotify = {
version = "...",
default-features = false,
features = ["client-ureq", "ureq-rustls-tls"]
}
§Proxies
Both reqwest and [ureq][ureq-proxying] support system
proxies by default. They both read http_proxy
, https_proxy
, all_proxy
and their uppercase variants HTTP_PROXY
, HTTPS_PROXY
, ALL_PROXY
,
although the specific logic implementations are a little different.
See also:
§Environmental variables
RSpotify supports the dotenvy
crate, which allows you to save credentials
in a .env
file. These will then be automatically available as
environmental values when using methods like Credentials::from_env
.
[dependencies]
rspotify = { version = "...", features = ["env-file"] }
§CLI utilities
RSpotify includes basic support for Cli apps to obtain access tokens by
prompting the user, after enabling the cli
feature. See the
Authorization section for more information.
§Getting Started
§Authorization
All endpoints require app authorization; you will need to generate a token that indicates that the client has been granted permission to perform requests. You can start by registering your app to get the necessary client credentials. Read the official guide for a detailed explanation of the different authorization flows available.
RSpotify has a different client for each of the available authentication
flows. They may implement the endpoints in
BaseClient
or
OAuthClient
according to what kind of
flow it is. Please refer to their documentation for more details:
- Client Credentials Flow: see
ClientCredsSpotify
. - Authorization Code Flow: see
AuthCodeSpotify
. - Authorization Code Flow with Proof Key for Code Exchange
(PKCE): see
AuthCodePkceSpotify
. - Implicit Grant Flow: unimplemented, as RSpotify has not been tested on a browser yet. If you’d like support for it, let us know in an issue!
In order to help other developers to get used to rspotify
, there are
public credentials available for a dummy account. You can test rspotify
with this account’s RSPOTIFY_CLIENT_ID
and RSPOTIFY_CLIENT_SECRET
inside
the .env
file
for more details.
§WebAssembly
RSpotify supports the wasm32-unknown-unknown
target in combination
with the client-reqwest
feature. HTTP requests must be processed async.
Other HTTP client configurations are not supported.
Spotify recommends using AuthCodePkceSpotify
for
authorization flows on the web.
Importing the Client ID via RSPOTIFY_CLIENT_ID
is not possible since WASM
web runtimes are isolated from the host environment. The client ID must be
passed explicitly to Credentials::new_pkce
. Alternatively, it can be
embedded at compile time with the std::env!
or
dotenv!
macros.
§Examples
There are some available examples on the GitHub repository which can serve as a learning tool.
Re-exports§
pub use rspotify_http as http;
pub use rspotify_macros as macros;
pub use rspotify_model as model;
Modules§
- Synchronization primitives that have both synchronous and asynchronous variants under the same interface.
Macros§
Structs§
- The Authorization Code Flow with Proof Key for Code Exchange (PKCE) client for the Spotify API.
- The Authorization Code Flow client for the Spotify API.
- The Client Credentials Flow client for the Spotify API.
- Struct to configure the Spotify client.
- Simple client credentials object for Spotify.
- Structure that holds the required information for requests with OAuth.
- Spotify access token information
- A callback function is invokved whenever successfully request or refetch a new token.
Enums§
- Possible errors returned from the
rspotify
client.