A Wrapper to work with the Spotidy Web API (https://developer.spotify.com/documentation/web-api/)
This library relies on Fetch API. And this API is supported in the following browsers.
39+ ✔ | 42+ ✔ | 29+ ✔ | 10.1+ ✔ | Nope ✘ |
This library depends on fetch to make requests to the Spotify Web API. For environments that don't support fetch, you'll need to provide a polyfill to browser or polyfill to Node.
$ npm install vs-spotify-api-wrapper --save
// import wrapper package
import spotifyApiWrapper from 'vs-spotify-api-wrapper';
// creating new instance
const spotify = new spotifyApiWrapper({
clientId: 'YOUR_SPOTIFY_CLIENT_ID',
redirectUri: 'ALLOWED_REDIRECT_URI'
});
// using a method
var albums = spotify.search.query('U2', 'album');
var spotifyApiWrapper = require('vs-spotify-api-wrapper');
const spotify = new spotifyApiWrapper({
clientId: 'YOUR_SPOTIFY_CLIENT_ID',
redirectUri: 'ALLOWED_REDIRECT_URI'
});
// using a method
var albums = spotify.search.query('U2', 'album');
<!--importing library-->
<script src="spotifyApiWrapper.umd.js"></script>
After that the library will be avaiable to the Global as spotifyApiWrapper
. Follow an example:
const spotify = new spotifyApiWrapper({
clientId: 'YOUR_SPOTIFY_CLIENT_ID',
redirectUri: 'ALLOWED_REDIRECT_URI'
});
const albums = spotify.search.query('U2', 'album');
To perform requests to the spotify API Endpoints an Access Token must be provided and to facilitate this process the Wrapper has a module responsible for dealing with this. The sessionManager Module offers a group of methods that can be used to not only request authentication but also parse the necessary response parameters provided by the spotify API. The authentication mode adopted was the Implicit Grant Flow. More information can be found at: (https://developer.spotify.com/documentation/general/guides/authorization-guide/#implicit-grant-flow).
Before you can request any information from the Spotify API an Access Token is required and to obtain one, the user must grant access to his information through the Spotify API OAuth Authentication Flow. As the Access Token is received it is stored by the wrapper and used in future requests alongside with it's expiration period. After it expires, another token must be provided. The following steps must be met before any request to the API is made:
- Check if the the Token (If any) has already expired (session.checkTokenExpiration() method)
- Request the user authorization if so (session.authorize() method)
- Parse the received hash parameters after the Spotify API Authorization redirects the user back to your application (session.getUriParams() method)
After these two steps, the requests can be made to the Spotify API using the provided methods. In the following Methods Section more details can be found related with the sessionManager available methods.
From version 1.2.1 the current access token is stored at the user localStorage for later usage, therefore preventing the user of being prompted by the Spotify API every page reload
Another feature is the cacheManager Module. With this is possible to cache the latest performed searchs and also the items chose by the user in your implementation. After performing a search operation, the query used is automatically stored at the search history alongside with it's response, if any, from the spotify API. User choices among the returned items can also be stored and they also contain related information like which query term was used, the item name itself and so on. Check the Methods section to see related information about the available methods.
. From version 1.1.0 an integration with the "localstorage" WebApi was introduced, so that the user can keep his search history for later usage. . At version 1.2.1 we no longer automatically stores the last term of a performed query. This way the developer can store the term at the moment that suits him better, enhancing debounce techniques and data flow.
When you perform a search using the "search.query" method two operations takes place:
- Before the request is sent to the Spotify API, the current access token retrieved previously has it's expiration period checked, if so, the user is automatically redirected to the Spotify API Authorization Page and a new permission will be requested.
- If the Current Access Token is valid, the search continues and if it's sucessful, the result is automatically cached using the "cache.storeItem" method. An item has the following structure:
{ search: ‘THE_SEARCHED_STRING’, type: ‘THE_REQUEST_TYPE’, response: [{…}, {…}] }
Where:
- search: Refers to the searched string provided by the user
- type: Refers to the spotify resource type being searched for: Album, Artist, Track or Playlist
- response: The actual Spotify Api response. Usually a list of Objects
In the following Methods Section a list with all the cacheManager methods will be provided
Follow the mehods that the libray provides
Search for a query item for a given type. Test in Spotify Web Console with type defined as album. See more related information at (https://developer.spotify.com/documentation/web-api/reference/search/search/)
Arguments
Argument | Type | Options |
---|---|---|
query |
string | 'Any search query' |
type |
string | 'Album', 'Artist', 'Track' and 'Playlist' |
Example
spotify.search.query('U2', 'Album')
.then(data => {
// do what you want with the data
})
Search for informations about a specific Album with provided id. Test in Spotify Web Console.
Arguments
Argument | Type | Options |
---|---|---|
id |
string | 'Specific id' |
Example
spotify.album.getAlbum('4aawyAB9vmqN3uQ7FjRGTy')
.then(data => {
// do what you want with the data
})
Search for informations about some Albums with all id's. Test in Spotify Web Console.
Arguments
Argument | Type | Options |
---|---|---|
ids |
Array of strings | ['id1', 'id2'] |
Example
spotify.album.getAlbums(['4aawyAB9vmqN3uQ7FjRGTy', '1A2GTWGtFfWp7KSQTwWOyo'])
.then(data => {
// do what you want with the data
})
Search for all tracks in a specific Album with provided id. Test in Spotify Web Console.
Arguments
Argument | Type | Options |
---|---|---|
id |
string | 'Specific id' |
Example
spotify.album.getTracks('4aawyAB9vmqN3uQ7FjRGTy')
.then(data => {
// do what you want with the data
})
Sets an option value
Arguments
Argument | Type | Options |
---|---|---|
option_name |
string | 'historySize', 'chosenSize' |
Options Available
- historySize: Sets the maximum size of the list that stores the searched items
- chosenSize: Sets the maximum size of the list that stores the items chosen by the user
- useLocalStorage: Enables the wrapper to storage the cached data into the Browser LocalStorage
Example
spotify.cache.setOptions('historySize', 3);
Stores an item received from a previous request to the spotify API into the cache list For a full list of the data model for each resource returned check: (https://developer.spotify.com/documentation/web-api/reference/object-model/)
Arguments
Argument | Type | Object Structure |
---|---|---|
item |
object | { search: 'searched_string', type: 'album', response: [{...}, {...}] } |
Item Structure
- search: The searched string by the user
- type: The type of the performed search ('album', 'artist', 'track' or 'playist')
- response: The spotify API response, usually an Array of Objects
Example
spotify.cache.storeItem({ search: 'u2', type: 'album', response: {[...]} });
Stores an item received from a previous request to the spotify API into the Chosen Items Cache list
Arguments
Argument | Type | Object Structure |
---|---|---|
choice |
object | { search: 'some_random_search', type: 'album', response: [{...}, {...}] } |
Item Structure
- search: The searched string by the user that originated the choice item as a response
- name: The item name string chose by the user
- id: The spotify API resource ID provided in the request response
- type: The type of the performed search ('album', 'artist', 'track' or 'playist')
Example
spotify.cache.storeChoice({ search: 'original-searched-item',
name: 'chosen-album-name',
id: 'some-random-album-id',
type: 'album' });
Get the items stored at the Cache List related with the query provided
Arguments
Argument | Type | Options |
---|---|---|
query |
string | 'some string to search by' |
Parameter description
- query: A string that may be present at the Cache List in the 'search' field of a Stored Item
Example
spotify.cache.getCachedData('my_previous_query_value');
Get the item stored at the Choices Cache List related with the provided Choice Item
Arguments
Argument | Type | Object Structure |
---|---|---|
choice |
object | { search: 'original-search', name: 'item-name', id: 'spotify-item-id', type: 'album' } |
Item Structure
- search: The searched string by the user that originated this item as a response
- name: The item name string chose by the user
- id: The spotify API resource ID provided in the request response
- type: The type of the performed search ('album', 'artist', 'track' or 'playist')
Example
const choice = { search: 'original-search', name: 'album-name', id: 'random-id', type: 'album' };
spotify.cache.getCachedChoiceData(choice);
Gets the full Cached List of searched items
Example
const history = spotify.cache.getHistory();
Response Structure The data returned is an Array of Objects that represents the searched history
[{ search: 'first_search', type: 'album', response: {} }, { search: 'second_search', type: 'track', response: {} }, ...]
Gets the full Cached List of Chosen Items by the User
Example
const choices = spotify.cache.getChosenAlbums();
Response Structure The data returned is an Array of Objects that represents the items chosen by the user
[{ search: 'original-search', name: 'album-name', id: 'random-id', type: 'album' }, { search: 'another-search', name: 'chosen-track-name', id: 'another-random-id', type: 'track' }, ...]
Redirects the user to the Spotify API Authorization Page where he is requested to grant/deny access to his data
Example
spotify.session.authorize();
Fetches the hash parameters included at url that the user is redirected after granting the App Permission
Example
spotify.session.getUriParams();
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
Vitor José |
This project is licensed under the MIT License - see the LICENSE.md file for details