SPTKit is a lightweight, elegant and easy to use Spotify Web API wrapper written in pure Swift. It is built around Swift's Codable to offer great perfomance and simplicity. SPTKit makes calls to Web API and returns clean, easy to use objects which can be then easily stored on the device via good old JSONEncoder.
- iOS 10+ / macOS 10.12+ / tvOS 10+ / watchOS 3+
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler. In order to do add SPTKit to your project, use the following URL:
https://github.com/wiencheck/SPTKit.git
SPTKit supports most of Web API's endpoints and methods. To use any of the methods you have to obtain an authorization token
SPTKit doesn't handle authorization with Spotify, you have to manage that yourself. How to do that is described in great depth
However, the Example app contains barebones code needed to perform the authorization. You'll still need to set you application in Spotify Dashboard before continuing.
After obtaining auth token, you have to tell framework about it:
SPT.authorizationToken = "my_unique_token"
Some methods have to declare user's country code to properly return available objects. SPTKit reads this information from Locale.current by default, but you can override it by setting
SPT.countryCode = "de"
To use methods provided by SPTKit you use Modules for each endpoint. Spotify's Web API has various endpoints for calling methods for albums, library, search etc. and that structure is reflected in SPTKit. Methods are contained inside modules and each module represents API endpoint like you'd see in the API reference docs
For example, to get an Album method, you'd use the Album module and its getAlbum method, like this:
SPT.Album.getAlbum(...
To read user's saved albums you use the Library module, like this
SPT.Library.getSavedAlbums(...
You get the idea.
Available modules are:
Some methods, which can return more than a few objects (like getting Playlist's tracks), return them wrapped in a paging objects instead.
It's a generic class that holds an array of objects, and some metadata like page's offset and URLs for calling next, or previous pages.
public class SPTPagingObject<T: Codable>: Codable {
public let items: [T]
public let limit: Int
public let next: URL?
public let offset: Int
public let previous: URL?
public let total: Int
public var canMakeNextRequest: Bool {
return next != nil
}
public var canMakePreviousRequest: Bool {
return previous != nil
}
...
}You would typically extract objects from current page and then try to obtain next page and repeat the process until reaching the last page. Example usage
func handlePage<T>(_ page: SPTPagingObject<T>) where T: Decodable {
print(page.items)
guard page.canMakeNextRequest else {
return
}
page.getNext { result in
switch result {
case .success(let newPage):
self.handlePage(newPage)
case .failure(let error):
print(error.localizedDescription)
}
}
}SPTPagingObject defines helper methods getNext and getPrevious to quickly obtain related pages.
There are 3 cases in which errors can be raised, each one returning different type of an error:
- Request error - Request couldn't be completed because of faulty internet connection or something like that
- Service error - Request sucseeded but was invalid. This can happen if authorization token was not provided, parameters passed to method were in incorrect format, etc. Example service error structure
{
"error": {
"status": 401,
"message": "Invalid access token"
}
}
- Decoding error. This type of error should not happen, but in case it does, what it means is that there was a change in returned JSON and it couldn't be decoded correctly. Or I screwed up something along the way, which we know can't happen, right? Please report if you encounter this error.
Not all methods from the Web API are supported at the moment. Especially podcasts are currently not existent in this library. I am still working on this library so if you need any methods that are not implemented yet, please create an issue or better, submit a PR!
SPTKit is available under the MIT license. See the LICENSE file for more info.