rspotify wraps the Spotify Web API as Ruby objects

The object model is the point, not the endpoint coverage

rspotify is a Ruby wrapper for the Spotify Web API, and it was designed with usability as its primary goal, so that you can forget the API and intuitively interact with your playlists, favorite artists, users and so on. The example the documentation gives is the whole pitch. You can write my_playlist.tracks.sort_by(&:popularity).last.album without having to think which API calls must be done, because rspotify fills the gaps for you. The feature list mentions full API endpoint coverage, but that is the least interesting of the three claims, because any wrapper can enumerate endpoints. The value is in the traversal. The search and fetch calls return real objects with relationships resolved, so an album has a release_date, images and available_markets, a track has a duration_ms, a track_number and a preview_url, and an artist has a popularity, genres and top_tracks. A developer who has used the raw API recognises how much boilerplate that removes.

Search returns objects you can walk

The search surface covers the entity types you would expect, and each returns a collection you can keep working with:

require 'rspotify'

artists = RSpotify::Artist.search('Arctic Monkeys')

arctic_monkeys = artists.first
arctic_monkeys.popularity      #=> 74
arctic_monkeys.genres          #=> ["Alternative Pop/Rock", "Indie", ...]
arctic_monkeys.top_tracks(:US) #=> (Track array)

The pattern repeats for the other types, with RSpotify::Album.search, RSpotify::Track.search and RSpotify::Playlist.search, and it is worth noting that a country code is passed where the API needs one, so top_tracks(:US) is a market-scoped call rather than a default. The same fluent style applies to finding by id, with a single find or an array of ids, and the array form is the one to reach for when you have a batch of ids from a previous response, since it saves one request per item:

ids = %w(2UzMpPKPhbcC8RbsmuURAZ 7Jzsc04YpkRwB1zeyM39wE)

my_tracks = RSpotify::Track.find(ids)
my_tracks.size #=> 2

There is also a user object with a uri attribute, RSpotify::User.find('guilhermesad') returning something whose uri is a spotify:user: string.

Authentication is client credentials first, and scopes come later

Some data require authentication, such as playlist details, and the documentation is direct that you get your credentials from the Spotify developer application page and paste them in. The first level is client credentials:

RSpotify.authenticate("<your_client_id>", "<your_client_secret>")

With that done you can read playlists in detail, browse featured content and more. The features that need it are listed in the example, and they span the Browse endpoints and the recommendation engine. RSpotify::Category.find('party') gives you a category whose playlists you can read, RSpotify::Category.list gives all the categories, RSpotify::Playlist.browse_featured takes a country, and RSpotify::Album.new_releases takes one. Recommendations are generated from seeds, and the three seed types are genres, tracks and artists, with the generated object exposing its tracks. Audio features are available per track, with danceability, energy and tempo as the examples given.

OmniAuth is how a Rails app gets a user token

When an application needs to act on a user's Spotify account, for example to create playlists from their taste or sync playlists with an external service, the flow switches from client credentials to a per user token. The documentation shows the whole arrangement. The application file authenticates the client, and an OmniAuth builder is registered in an initializer with the scope string, which for a read and modify application is user-read-email, playlist-modify-public, user-library-read and user-library-modify:

require 'rspotify/oauth'

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :spotify, "<your_client_id>", "<your_client_secret>", scope: 'user-read-email playlist-modify-public user-library-read user-library-modify'
end

OmniAuth.config.allowed_request_methods = [:post, :get]

The documentation says to replace the scope values with the ones your own app will require, and links the list of available scopes. The allowed request methods line is not decorative, because it is what makes the sign-in link work. The link itself is a link_to with a method of :post, and the route is a get on /auth/spotify/callback to users#spotify. The callback address has to be added to the Redirect URIs list in your application page, with an example of http://localhost:3000/auth/spotify/callback. That last requirement is the one that trips people up in development, because the exact URL including port must be registered.

The user object can create playlists and edit the library

Once the callback arrives, the controller turns the OmniAuth hash into an RSpotify user, and that object is the privileged one:

class UsersController < ApplicationController
  def spotify
    spotify_user = RSpotify::User.new(request.env['omniauth.auth'])
    # Now you can access user's private data, create playlists and much more

    # Access private data
    spotify_user.country #=> "US"
    spotify_user.email   #=> "[email protected]"

    # Create playlist in user's Spotify account
    playlist = spotify_user.create_playlist!('my-awesome-playlist')

The methods that mutate are marked with a trailing exclamation mark, which is a Ruby convention that signals the call performs a write, and the list on the user object is long. You can add tracks to a playlist with add_tracks!, save and remove tracks in the library with save_tracks! and remove_tracks!, do the same for albums with save_albums! and remove_albums!, and use the follow features with follow. The distinction matters in review, because a bang method that hits a remote API and mutates a user's library is the kind of thing you want visible at the call site, and the naming makes it visible.

A small gem with a narrow dependency surface

The repository is small and conventional for a Ruby gem, with a gemspec file, a Gemfile, a Rakefile, a .rspec file, lib/ and spec/ directories, an .editorconfig and a .github directory for the workflow that produces the build status badge. The full documentation is generated on rubydoc, and the README points to the frames index for the complete reference rather than repeating it. What is notable is what is not in the repository. There is no vendored copy of the Spotify API, no schema file, and no server side component, because the gem is a client for a remote API rather than an implementation of one. The library therefore has no opinion on caching, on retry behaviour or on rate limit handling beyond what the underlying HTTP layer does, and the wrapper's job ends at the object graph. The licence is MIT, there are no GitHub releases, and the last push was on 2026-09-16, so the version marker is the commit. The practical risk to weigh is not the gem but the platform, since every method here depends on an endpoint and a scope policy that Spotify controls.

Editorial conclusion

Adopt rspotify when you are building a Ruby or Rails service that reads or writes Spotify data and want object methods instead of raw endpoint calls, and when the OAuth scope and redirect URI rules are acceptable. Do not adopt it if you need offline data, since every call is a live API request, and do not expect it to bypass the platform's authorisation rules. Verify first that the scopes you request in the OmniAuth builder match what your application actually uses, that the callback URL is registered in the Spotify application page, and that the endpoints you rely on are still in the current Spotify Web API surface.

Frequently asked questions

Official sources

1. guilhermesad/rspotify on GitHub
2. Issues
3. License: MIT
4. README