finish the readme, a few changes make all our lives easier

Author: adamint

README.md

@@ -77,7 +77,22 @@ time, this will likely be accurate within a few milliseconds.
 
 ## Using the Library
 ### The benefits of LinkedResults, PagingObjects, and Cursor-based Paging Objects
-tbd
+Spotify provides these three object models in order to simplify our lives as developers. So let's see what we
+can do with them!
+
+#### PagingObjects
+PagingObjects are a container for the requested objects (`items`), but also include 
+important information useful in future calls. It contains the request's `limit` and `offset`, along with 
+(sometimes) a link to the next and last page of items and the total number of items returned.
+
+#### Cursor-Based Paging Objects
+A cursor-based paging object is a PagingObject with a cursor added on that can be used as a key to find the next 
+page of items
+
+#### LinkedResults
+Some endpoints, like `PlaylistsAPI.getPlaylistTracks`, return a LinkedResult, which is a simple wrapper around the 
+list of objects. With this, we have access to its Spotify API url (with `href`), and we provide simple methods to parse 
+that url.
 
 ### Generic Request
 ```kotlin
@@ -99,7 +114,16 @@ tbd
 ```
 
 ### Track Relinking
-tbd
+Spotify keeps many instances of most tracks on their servers, available in different markets. As such, if we use endpoints 
+that return tracks, we do not know if these tracks are playable in our market. That's where track relinking comes in.
+
+To relink in a specified market, we must supply a `market` parameter for endpoints where available. 
+In both Track and SimpleTrack objects in an endpoint response, there is a nullable field called `linked_from`. 
+If the track is unable to be played in the specified market and there is an alternative that *is* playable, this 
+will be populated with the href, uri, and, most importantly, the id of the track.
+
+You can then use this track in client actions such as playing or saving the track, knowing that it will be playable 
+in your market!
 
 ### Endpoint List
 #### SpotifyAPI:

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/follow/UserFollowAPI.kt

@@ -121,7 +121,17 @@ class UserFollowAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
-
+    /**
+     * Add the current user as a follower of a playlist.
+     *
+     * @param ownerId The Spotify user ID of the person who owns the playlist.
+     * @param playlistId The Spotify ID of the playlist. Any playlist can be followed, regardless of its
+     * public/private status, as long as you know its playlist ID.
+     * @param followPublicly Defaults to true. If true the playlist will be included in user’s public playlists,
+     * if false it will remain private. To be able to follow playlists privately, the user must have granted the playlist-modify-private scope.
+     *
+     * @throws BadRequestException if the playlist is not found
+     */
     fun followPlaylist(ownerId: String, playlistId: String, followPublicly: Boolean = true): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             put("https://api.spotify.com/v1/users/$ownerId/playlists/$playlistId/followers", "{\"public\": $followPublicly}")
@@ -130,20 +140,68 @@ class UserFollowAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
 
     }
 
+    /**
+     * Remove the current user as a follower of another user
+     *
+     * @param userId The user to be unfollowed from
+     *
+     * @throws BadRequestException if [userId] is not found
+     */
+    fun unfollowUser(userId: String): SpotifyRestAction<Unit> {
+        return toAction(Supplier {
+            unfollowUsers(userId).complete()
+        })
+    }
+
+    /**
+     * Remove the current user as a follower of other users
+     *
+     * @param userIds The users to be unfollowed from
+     *
+     * @throws BadRequestException if an invalid id is provided
+     */
     fun unfollowUsers(vararg userIds: String): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             delete("https://api.spotify.com/v1/me/following?type=user&ids=${userIds.joinToString(",") { it.encode() }}")
             Unit
         })
     }
 
+    /**
+     * Remove the current user as a follower of an artist
+     *
+     * @param artistId The artist to be unfollowed from
+     *
+     * @throws BadRequestException if an invalid id is provided
+     */
+    fun unfollowArtist(artistId: String): SpotifyRestAction<Unit> {
+        return toAction(Supplier {
+            unfollowArtists(artistId).complete()
+        })
+    }
+
+    /**
+     * Remove the current user as a follower of artists
+     *
+     * @param artistIds The artists to be unfollowed from
+     *
+     * @throws BadRequestException if an invalid id is provided
+     */
     fun unfollowArtists(vararg artistIds: String): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             delete("https://api.spotify.com/v1/me/following?type=artist&ids=${artistIds.joinToString(",")}")
             Unit
         })
     }
 
+    /**
+     * Remove the current user as a follower of a playlist.
+     *
+     * @param ownerId The Spotify user ID of the person who owns the playlist.
+     * @param playlistId The Spotify ID of the playlist that is to be no longer followed.
+     *
+     * @throws BadRequestException if the playlist is not found
+     */
     fun unfollowPlaylist(ownerId: String, playlistId: String): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             delete("https://api.spotify.com/v1/users/$ownerId/playlists/$playlistId/followers")

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/personalization/PersonalizationAPI.kt

@@ -8,6 +8,7 @@ import java.util.function.Supplier
  * Endpoints for retrieving information about the user’s listening habits.
  */
 class PersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+
     fun getTopArtists(): SpotifyRestAction<PagingObject<Artist>> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/me/top/artists").toPagingObject<Artist>(api = api)

src/main/kotlin/com/adamratzman/spotify/endpoints/priv/users/UserAPI.kt

@@ -11,6 +11,15 @@ import java.util.function.Supplier
  * Endpoints for retrieving information about a user’s profile.
  */
 class UserAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
+    /**
+     * Get detailed profile information about the current user (including the current user’s username).
+     *
+     * The access token must have been issued on behalf of the current user.
+     * Reading the user’s email address requires the user-read-email scope; reading country and product subscription level
+     * requires the user-read-private scope. Reading the user’s birthdate requires the user-read-birthdate scope.
+     *
+     * @return Never-null [SpotifyUserInformation] object with possibly-null country, email, subscription and birthday fields
+     */
     fun getUserProfile(): SpotifyRestAction<SpotifyUserInformation> {
         return toAction(Supplier {
             get("https://api.spotify.com/v1/me").toObject<SpotifyUserInformation>(api)

src/main/kotlin/com/adamratzman/spotify/utils/Helpers.kt

@@ -6,6 +6,7 @@ import com.google.gson.Gson
 import org.json.JSONObject
 import org.jsoup.Connection
 import org.jsoup.Jsoup
+import java.io.InvalidObjectException
 import java.net.URLEncoder
 import java.util.*
 import java.util.function.Supplier
@@ -58,24 +59,24 @@ data class PlaylistTrackPagingObject(val href: String, val items: List<PlaylistT
 data class SimpleTrackPagingObject(val href: String, val items: List<SimpleTrack>, val limit: Int, val next: String? = null, val offset: Int = 0, val previous: String? = null, val total: Int)
 
 data class LinkedResult<out T>(val href: String, val items: List<T>) {
-    fun toPlaylistParams(): PlaylistParams? {
+    fun toPlaylistParams(): PlaylistParams {
         if (href.startsWith("https://api.spotify.com/v1/users/")) {
             val split = href.removePrefix("https://api.spotify.com/v1/users/").split("/playlists/")
             if (split.size == 2) return PlaylistParams(split[0], split[1].split("/")[0])
         }
-        return null
+        throw InvalidObjectException("This object is not linked to a playlist")
     }
-    fun getArtistId(): String? {
+    fun getArtistId(): String {
         if (href.startsWith("https://api.spotify.com/v1/artists/")) {
             return href.removePrefix("https://api.spotify.com/v1/artists/").split("/")[0]
         }
-        return null
+        throw InvalidObjectException("This object is not linked to an artist")
     }
-    fun getAlbumId(): String? {
+    fun getAlbumId(): String {
         if (href.startsWith("https://api.spotify.com/v1/albums/")) {
             return href.removePrefix("https://api.spotify.com/v1/albums/").split("/")[0]
         }
-        return null
+        throw InvalidObjectException("This object is not linked to an album")
     }
 }
 

src/main/kotlin/com/adamratzman/spotify/utils/ResultObjects.kt

@@ -20,9 +20,9 @@ data class PlaylistTrackInfo(val href: String, val total: Int)
  */
 data class Followers(val href: String?, val total: Int)
 
-data class SpotifyUserInformation(val birthdate: String, val country: String, val display_name: String?, val email: String,
+data class SpotifyUserInformation(val birthdate: String?, val country: String?, val display_name: String?, val email: String?,
                                   val external_urls: HashMap<String, String>, val followers: Followers, val href: String,
-                                  val id: String, val images: List<SpotifyImage>, val product: String, val type: String,
+                                  val id: String, val images: List<SpotifyImage>, val product: String?, val type: String,
                                   val uri: String)
 
 data class SpotifyPublicUser(val display_name: String, val external_urls: HashMap<String, String>, val followers: Followers, val href: String,