Crate spotify_rs

source ·
Expand description

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.

You will need to set a redirect URI, which you’ll need to pass to spotify-rs and is recommended you use. You’ll also need the client ID and possibly the client secret of your app, depending on the authorisation flow you’re going to use.

To use the Spotify API, you’ll need to authenticate using your client credentials, and if you want to access user resources, you’ll need to go through one of the authorisation flows.

Authorisation

You will need to set some scopes, redirect the user to a generated URL, which will redirect them again to your app’s redirect URI, which will contain a code that allows your app to be authorised.

spotify-rs supports 3 of the 4 OAuth2 authorisation flows the API supports: 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;
  • 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, AuthCodeFlow, RedirectUrl};


#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
     // This should match the redirect URI you set in your app's settings
    let redirect_url = RedirectUrl::new("redirect_url".to_owned())?;
    let auto_refresh = true;
    let scopes = vec!["user-library-read", "playlist-read-private"];
    let auth_code_flow = AuthCodeFlow::new("client_id", "client_secret", scopes);

    // Redirect the user to this URL to get the auth code and CSRF token
    let (client, url) = AuthCodeClient::new(auth_code_flow, redirect_url, auto_refresh);

    // They will then have to be redirected to the `redirect_url` you specified,
    // with those two parameters present in the URL

    // Finally, exchange the auth code for an access token
    let mut spotify = client.authenticate("auth_code", "csrf_token").await?;

    // Get an album with the specified ID (requires no scopes to be set)
    let album = spotify.album("album_id").get().await?;

    // The `album` method returns a builder with optional parameters you can set
    // For example, this sets the market to "GB".
    let album_gb = spotify.album("album_id").market("GB").get().await?;

    // Get 5 of the current user's playlists (requires the playlist-read-private scope)
    let user_playlists = spotify.current_user_playlists().limit(5).get().await?;

    Ok(())
}

The Authorisation Code Flow with PKCE is the same, except you would need to use AuthCodePkceFlow and AuthCodeClient.

The list of available scopes can be found here.

You can see all of the available optional parameters in the Builder documentation. They show up after each impl Builder<'_, F, SomeEndpoint, where SomeEndpoint represents the endpoint you’re calling.

The auth code and CSRF token can be obtained by parsing the URL the user was redirected to from the url returned from .get_authorisation.

That could be achieved by simply having the user copy and paste the URL into your app, or, the recommended approach, 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.

Client Credentials Flow

use spotify_rs::{ClientCredsClient, ClientCredsFlow, RedirectUrl};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let auth_flow = ClientCredsFlow::new("client_id", "client_secret");

    // Create an authenticate the client
    let mut spotify = ClientCredsClient::authenticate(auth_flow).await?;

    let album = spotify.album("album_id").get().await?;

    Ok(())
}

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

You can see all of the available optional parameters in the Builder documentation. They show up after each impl Builder<'_, F, SomeEndpoint, where SomeEndpoint represents the endpoint you’re calling.

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.

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

Re-exports

Modules

Structs

  • Nil
    Represents an empty API response.
  • RedirectUrl
    URL of the client’s redirection endpoint.

Enums

  • Error
    An error returned by the client in a custom Result.

Type Aliases