Crate rspotify

source ·
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:

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§

Modules§

  • clients
  • prelude
  • sync
    Synchronization primitives that have both synchronous and asynchronous variants under the same interface.

Macros§

  • scopes
    Create a HashSet from a list of &str to easily create scopes for Token or OAuth.

Structs§

Enums§

Constants§

Type Aliases§