gruncan / spotify4java

Spotify Java API Wrapper

Spotify for Java (Still under development)

Spotify api wrapper for java. JavaDocs

Written for enjoyment and a way to learn java concepts that I have rarely/never used. Demonstrated usage of OAuth 2.0 and java reflections, generics, networking, and concurrency.

Latest: v1.5.0

Maven

<dependency>
    <groupId>dev.gruncan.s4j</groupId>
    <artifactId>S4J</artifactId>
    <version>1.5.0</version>
</dependency>

Version Roadmap

• v1.0.0: WebAPI
• v2.0.0: AdAPI
• v3.0.0: Embeds
• v4.0.0: Open Access

Most often all rquests will be implemented before x.5.0 and all serialization before next major version

How it do

Firstly create an app at spotify's dashboard https://developer.spotify.com/dashboard/applications

Example:

SpotifyClient spotifyClient = new SpotifyClientBuilder("CLIENT_ID", "CLIENT_SECRET", "REDIRECT_URL")
                                                        .getBuiltClient();

• CLIENT_ID is found at your newly create app's dashboard
• CLIENT_SECRET is again found at your app's dashboard
• REDRIECT_URL has to be set in your app's dashboard

getBuiltClient() will make/create the necessary requests/server following spotify's OAuth 2.0 authentication framework

If however you already have an access_token you can use:

SpotifyClient spotifyClient = SpotifyClient.buildFromToken("access_token");

Executing Requests

Executing a request is as simple as instantiating your chosen request class with selected constructor parameters for said request and executing it with your spotifyClient executeRequest

Example:

public static void main(String[] args){
    SpotifyClient spotifyClient = new SpotifyClientBuilder("CLIENT_ID", "CLIENT_SECRET", "REDIRECT_URL").getBuiltClient();
    TrackGet trackGet = new TrackGet("Track_id");
    SpotifyResponse response = spotifyClient.executeRequest(trackGet);
    JSONObject jsonObject = response.getJsonObject();
    System.out.println(jsonObject.toString());
}

Returns a SpotifyResponse that encapsulates the json response from the spotify api

All Json classes were taken from https://github.com/tdunning/open-json with only minor edits.

Requests modelled by this api so far

Album:

• AlbumGet (api.spotify.com/v1/albums/{id})
• AlbumTracksGet (api.spotify.com/v1/albums/{id}/tracks)
• AlbumSeveralGet (api.spotify.com/v1/albums)
• AlbumReleasesGet (api.spotify.com/v1/browse/new-releases)

Artists:

• ArtistGet (api.spotify.com/v1/artists/{id})
• ArtistsAlbumsGet (api.spotify.com/v1/artists/{id}/albums)
• ArtistsRelatedArtistsGet (api.spotify.com/v1/artists/related-artists)
• ArtistsTopTracksGet (api.spotify.com/v1/artists/{id}/top-tracks)
• ArtistSeveralGet (api.spotify.com/v1/artists)

Audiobooks:

• AudiobookGet (api.spotify.com/v1/audiobooks/{id})
• AudiobookSeveralGet (api.spotify.com/v1/audiobooks/)
• AudiobookChaptersGet (api.spotify.com/v1/audiobooks/{id}/chapters)

Categories:

• CategoryGet (api.spotify.com/v1/browse/categories/{category_id})
• CategorySeveralGet (api.spotify.com/v1/browse/categories)

Chapters:

• ChapterGet (api.spotify.com/v1/chapters/{id})
• ChapterSeveralGet (api.spotify.com/v1/chapters)

Episodes:

• EpisodeGet (api.spotify.com/v1/episodes/{id})
• EpisodeSeveralGet (api.spotify.com/v1/episodes)

Genres:

• GenreAvailableGet (api.spotify.com/v1/recommendations/available-genre-seeds)

Markets:

• MarketsAvailableGet (api.spotify.com/v1/markets)

Me:

• MyAlbumsDelete (api.spotify.com/v1/me/albums)

• MyAlbumsGet (api.spotify.com/v1/me/albums)

• MyAlbumsPut (api.spotify.com/v1/me/albums)

• MyAlbumsSavedGet (api.spotify.com/v1/me/albums)

• MyAudiobooksDelete (api.spotify.com/v1/me/audiobooks)

• MyAudiobooksGet (api.spotify.com/v1/me/audiobooks)

• MyAudiobooksPut (api.spotify.com/v1/me/audiobooks)

• MyAudiobooksSavedGet (api.spotify.com/v1/me/audiobooks)

• MyEpisodesDelete (api.spotify.com/v1/me/episodes)

• MyEpisodesGet (api.spotify.com/v1/me/episodes)

• MyEpisodesPut (api.spotify.com/v1/me/episodes)

• MyEpisodesSavedGet (api.spotify.com/v1/me/episodes)

• MyFollowedArtistsGet (api.spotify.com/v1/me/following)

• MyFollowingPersonGet (api.spotify.com/v1/me/following/contains)

• MyFollowPersonPut (api.spotify.com/v1/me/following)

• MyProfileGet (api.spotify.com/v1/me)

• MyTopInfo (api.spotify.com/v1/me/top/{type})

• MyUnfollowPersonDelete (api.spotify.com/v1/me/following)

• MyPlayerCurrentlyPlayingGet (api.spotify.com/v1/me/player/currently-playing)

• MyPlayerDevicesGet (api.spotify.com/v1/me/player/devices)

• MyPlayerGet (api.spotify.com/v1/me/player)

• MyPlayerNextPost

• MyPlayerPausePut (api.spotify.com/v1/me/player/pause)

• MyPlayerPreviousPost

• MyPlayerQueueGet (api.spotify.com/v1/me/player/queue)

• MyPlayerQueuePost

• MyPlayerRecentlyPlayedGet (api.spotify.com/v1/me/player/recently-played)

• MyPlayerRepeatPut (api.spotify.com/v1/me/player/repeat)

• MyPlayerResumePut (api.spotify.com/v1/me/player/play)

• MyPlayerSeekPut (api.spotify.com/v1/me/player/seek)

• MyPlayerSetVolumePut (api.spotify.com/v1/me/player/volume)

• MyPlayerToggleShufflePut (api.spotify.com/v1/me/player/shuffle)

• MyPlayerTransferPut (api.spotify.com/v1/me/player)

• MyPlaylistsGet (api.spotify.com/v1/me/playlists)

• MyShowsDelete (api.spotify.com/v1/me/shows)

• MyShowsGet (api.spotify.com/v1/me/shows)

• MyShowsPut (api.spotify.com/v1/me/shows)

• MyShowsSavedGet (api.spotify.com/v1/me/shows)

• MyTracksDelete (api.spotify.com/v1/me/tracks)

• MyTracksGet (api.spotify.com/v1/me/tracks)

• MyTracksPut (api.spotify.com/v1/me/tracks)

• MyTracksSavedGet (api.spotify.com/v1/me/tracks)

Playlists:

• PlaylistGet (api.spotify.com/v1/playlists/{playlist_id})
• PlaylistCategoriesGet (api.spotify.com/v1/browse/categories/{category_id}/playlists)
• PlaylistFeaturedGet (api.spotify.com/v1/browse/featured-playlists)
• PlaylistImageGet (api.spotify.com/v1/playlists/{playlist_id}/images)
• PlaylistTracksGet api.spotify.com/v1/playlists/{playlist_id}/tracks)
• PlaylistAddCoverImagePut (/api.spotify.com/v1/playlists/{playlist_id}/images)
• PlaylistAddItemPost (api.spotify.com/v1/playlists/{playlist_id}/tracks)
• PlaylistChangeDetailsPut (api.spotify.com/v1/playlists/{playlist_id})
• PlaylistFollowingCheckGet (api.spotify.com/v1/playlists/{playlist_id}/followers/contains)
• PlaylistFollowPut (api.spotify.com/v1/playlists/{playlist_id}/followers)
• PlaylistRemoveItemDelete (api.spotify.com/v1/playlists/{playlist_id}/tracks)
• PlaylistUnfollowDelete (api.spotify.com/v1/playlists/{playlist_id}/followers)
• PlaylistUpdatePut (api.spotify.com/v1/playlists/{playlist_id}/tracks)

Search:

• SearchGet (api.spotify.com/v1/search)

Shows:

• ShowGet (api.spotify.com/v1/shows/{id})
• ShowSeveralGet (api.spotify.com/v1/shows)
• ShowEpisodesGet (api.spotify.com/v1/shows/{id}/episodes)

Tracks:

• TrackAudioFeatureSeveralGet (api.spotify.com/audio-features)
• TrackSeveralGet (api.spotify.com/tracks)
• TrackAudioAnalysisGet (api.spotify.com/audio-analysis/{id})
• TrackAudioFeaturesGet (api.spotify.com/audio-features/{id})
• TrackGet (api.spotify.com/tracks/{id})
• TrackRecommendationGet (api.spotify.com/recommendations)

User:

• UserPlaylistCreatePost (api.spotify.com/v1/users/{user_id}/playlists)
• UserPlaylistGet (api.spotify.com/v1/users/{user_id}/playlists)
• UserProfileGet (api.spotify.com/v1/users/{user_id})

Scored through requests are implemented but API endpoints do not work on spotify's end.

Future Plans

• Bring back Spring support for handling user authentication
• Add more branches of api requests not just web api
• Optimise multiple call different threads

spotify4java's Issues

Update readme to match requests

Update readme to match currently implemented requests

Implement serialization

Add serialization for currently implemented requests

Add documentation for requests

Generate javadocs for the core implementation of the api wrapper