Crate spotify_rs

spotify-rs is a Rust wrapper for the Spotify API. It has full API coverage and supports all the authorisation flows (except for the implicit grant flow).

Getting Started

First, you’ll need to create an app on Spotify’s developer dashboard.

There you will need to set a redirect URL. You’ll need to get the client ID, and possibly the client secret and redirect URL, depending on the authorisation flow you’re going to use.

There are two concepts: authenticating - that is, “logging the app in”, using your client ID and secret - and authorisation - which means having a user grant your app access to their account.

Depending on your chosen auth flow, there is either one step or two required to get you up and running.

Authorisation

You will need to set your scopes, redirect the user to a URL returned by spotify-rs, which will redirect them again to your app’s redirect URL, which will contain a code that allows your app to be authorised.

spotify-rs supports 3 of the 4 OAuth2 authorisation flows the API makes available: the authorisation code flow, authorisation code with PKCE flow and the client credentials flow.

The implicit grant flow is not supported for 2 reasons:

• it returns the access token in the URL, which is insecure and leaves your app vulnerable to all kinds of attacks;
• it doesn’t support refreshing the access token.

The auth flow you should use depends on the use case:

• the authorisation code flow is recommended for long-running applications where you can safely store the client secret (e.g. web and mobile apps)
• the authorisation code with PKCE flow is recommended for long-running applications where you can’t safely store the client secret (e.g. desktop apps and single page web apps)
• the client credentials flow doesn’t include authorisation, thus letting you only access public information

Below is an example for each auth flow:

Authorisation Code Flow

use spotify_rs::{AuthCodeClient, RedirectUrl};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Your application scopes
    let scopes = vec![
        "user-read-private",
        "playlist-modify-public",
        "playlist-modify-private",
        "playlist-read-private",
        "playlist-read-collaborative",
    ];

    // This should match the redirect URL you set in your app's settings
    // (on the Spotify API dashboard)
    let redirect_uri = RedirectUrl::new("your_redirect_url".to_owned())?;;

    // Whether or not to automatically refresh the token when it expires.
    let auto_refresh = true;

    // You will need to redirect the user to this URL.
    let (client, url) = AuthCodeClient::new(
        "client_id",
        "client_secret",
        scopes,
        redirect_uri,
        auto_refresh,
    );

    // After the user was redirected to `url`, they will be redirected *again*, to
    // your `redirect_uri`, with the "auth_code" and "csrf_state" parameters in the URL.
    // You will need to get those parameters from the URL.

    // Finally, you will be able to authenticate the client.
    let spotify = client.authenticate("auth_code", "csrf_state").await?;

    // Get an album with the specified ID.
    let album = spotify_rs::album("album_id").get(&spotify).await?;
    println!("The name of the album is: {}", album.name);

    // The `album` method returns a builder with optional parameters you can set
    // For example, this sets the market to "GB".
    let album_gb = spotify_rs::album("album_id")
        .market("GB")
        .get(&spotify)
        .await?;
    println!("The popularity of the album is {}", album_gb.popularity);

    // This gets 5 playlists of the user that authorised the app
    // (it requires the playlist-read-private scope).
    let user_playlists = spotify_rs::current_user_playlists()
        .limit(5)
        .get(&spotify)
        .await?;
    let result_count = user_playlists.items.len();
    println!("The API returned {} playlists.", result_count);

    Ok(())
}

The Authorisation Code Flow with PKCE is the same, except you would need to use AuthCodePkceClient instead of AuthCodeClient.

A of available scopes can be found here.

The auth code and CSRF token can be obtained by parsing the URL the user was redirected to (the redirect URL, as set in the API dashboard and when creating the client).

Please note that the redirect URL you pass to authenticate must match the redirect URL you set in the Spotify API developer dashboard.

That could be achieved by simply having the user copy and paste the URL into your app, or, for example, by having a server listening at your redirect_url and sending the auth code and CSRF token to the main app when the user is redirected to said URL.

For examples, check out the examples directory.

Client Credentials Flow

use spotify_rs::{ClientCredsClient, RedirectUrl};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let spotify = ClientCredsClient::authenticate("client_id", "client_secret").await?;

    // Get an album with the specified ID.
    let album = spotify_rs::album("album_id").get(&spotify).await?;
    println!("The name of the album is: {}", album.name);

    // The `album` method returns a builder with optional parameters you can set
    // For example, this sets the market to "GB".
    let album_gb = spotify_rs::album("album_id")
        .market("GB")
        .get(&spotify)
        .await?;
    println!("The popularity of the album is {}", album_gb.popularity);

    Ok(())
}

This flow doesn’t require anything besides the client credentials, but you cannot access any user information.

Automatic Token Refreshing

If auto_refresh is set to true when creating the client, on every request the client will check if the token is about to expire. If the token is close to expiring, it will refresh the token for you.

Note: this means that if the token has expired, the RwLock holding the Token will be acquired in order to change the token.

If you disable this feature, you’ll have to refresh the token yourself using request_refresh_token.

Re-exports

pub use client::AuthCodeClient;

pub use client::AuthCodePkceClient;

pub use client::ClientCredsClient;

Modules

client

Struct and methods for constructing and authenticating Clients.

endpoint

Functions and builders for all the Spotify endpoints.

model

Mappings of objects received from the Spotify API.

Structs

AuthCodePkceFlow

Represents the Authorisation Code Flow with PKCE extension, as defined in OAuth2 RFC 6749 and OAuth2 RFC 7636.

ClientCredsFlow

Represents the Client Credentials Flow, as defined in OAuth2 RFC 6749.

Nil

Represents an empty API response.

RedirectUrl

URL of the client’s redirection endpoint.

Token

An OAuth2 token.

Unauthenticated

Internal implementation details (typestate pattern), may change without warning.

Enums

Error

Type Aliases

SpotifyResult

A convenience result type that uses Error by default.