Skip to content

RetroAchievements/api-kotlin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

34 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RetroAchievements Logo

RetroAchievements Web API Client

Installation

To begin, import the library using jitpack.io.

You can include jitpack in your pom.xml by adding the following jitpack repository:

<repository>
    <id>jitpack.io</id>
    <url>https://www.jitpack.io</url>
</repository>

Then add this api-kotlin dependency to your pom.xml project!

<dependency>    
    <groupId>com.github.RetroAchievements</groupId>    
    <artifactId>api-kotlin</artifactId>    
    <version>1.0.10</version>
</dependency>

Usage

Basic Usage

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// access the api interface in `api`

Achievements

GetAchievementUnlocks

A call to this function will retrieve a list of users who have earned an achievement, targeted by the achievement's ID.

Available Parameters

Name Type Description Example
achievementId Int The achievement ID you'd like to query for 12345
count Int number of records to return (default: 50, max: 500). 10
offset Int number of entries to skip. 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementUnlocks.Response, ErrorResponse> = api.getAchievementUnlocks(
    achievementId = 13876
)

if (response is NetworkResponse.Success) {
    // handle the data
    val achievements: GetAchievementUnlocks.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Consoles

GetGameList

A call to this endpoint will retrieve the complete list of games for a specified console on the site, targeted by the console ID. If you do not know the console ID you're looking for, try using the all systems endpoint.

Warning, it's recommended to cache these results, as it is subject to rate-limiting & security measures.

Available Parameters

Name Type Description Example
consoleId Int The console ID you'd like to query for 1

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGameList.Response, ErrorResponse> = api.getGameList(
    consoleId = 1
)

if (response is NetworkResponse.Success) {
    // handle the data
    val gameList: GetGameList.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetConsoleIds

A call to this endpoint will retrieve the complete list of all system ID and name pairs on the site.

Available Parameters

Name Type Description Example Default
activeSystemsOnly Int Obtain active systems only 1 0
gameSystemsOnly Int Obtain game systems only 1 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetConsoleID.Response, ErrorResponse> = api.getConsoleIds()

if (response is NetworkResponse.Success) {
    // handle the data
    val consoleIds: GetConsoleID.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Events

GetAchievementOfTheWeek

A call to this endpoint will retrieve comprehensive metadata about the current Achievement of the Week.

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementOfTheWeek.Response, ErrorResponse> = api.getAchievementOfTheWeek()

if (response is NetworkResponse.Success) {
    // handle the data
    val achievementOfTheWeek: GetAchievementOfTheWeek.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Feed

GetActiveClaims

A call to this function returns information about all (1000 max) active set claims.

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetClaims.Response, ErrorResponse> = api.getActiveClaims()

if (response is NetworkResponse.Success) {
    // handle the data
    val claims: GetClaims.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetClaims

A call to this function returns information about all (1000 max) set claims of a specified kind.

Available Parameters

Name Type Description Example
claimKind Int The desired claim kind: 1 (completed), 2 (dropped), or 3 (expired). Defaults to 1. 1

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetClaims.Response, ErrorResponse> = api.getClaims(
    claimKind = 2
)

if (response is NetworkResponse.Success) {
    // handle the data
    val claims: GetClaims.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetTopTenUsers

A call to this function will retrieve the current top ten users on the site.

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetTopTenUsers.Response, ErrorResponse> = api.getTopTenUsers()

if (response is NetworkResponse.Success) {
    // handle the data
    val topUsers: GetTopTenUsers.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Games

GetAchievementDistribution

A call to this endpoint will retrieve a dictionary of the number of players who have earned a specific number of achievements for a given game ID. This endpoint can be used to determine the total mastery count for a game, as well as how rare that overall mastery is.

Available Parameters

Name Type Description Example
gameId Long The game ID you'd like to search for 14402
hardcore Int Fetching for hardcore achievements only (Hardcore-Only: 1, Default: 0) 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementDistribution.Response, ErrorResponse> = api.getAchievementDistribution(
    gameId = 14402,
    hardcore = 1
)

if (response is NetworkResponse.Success) {
    // handle the data
    val distribution: GetAchievementDistribution.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetAchievementCount

A call to this endpoint will retrieve the list of achievement IDs for a game, targeted by game ID. This can be useful if you'd like to quickly check how many achievements a particular game has. Using this, you can also detect if a game has received a revision. For example, if a game had 100 achievements last month and has 102 today, you know the game's achievement set has been revised.

Available Parameters

Name Type Description Example
gameId Long The game ID you'd like to search for 14402

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementCount.Response, ErrorResponse> = api.getAchievementCount(
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val achievementCount: GetAchievementCount.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetGameExtended

A call to this endpoint will retrieve extended metadata about a game, targeted via its unique ID.

Available Parameters

Name Type Description Example
gameId Long The game ID you'd like to search for 14402
unofficial Int Defaults to 3. Set to 5 to see Unofficial / demoted achievements. 3

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGameExtended.Response, ErrorResponse> = api.getGameExtended(
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val gameExtended: GetGameExtended.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetGameRankAndScore

A call to this function will retrieve metadata about either the latest masters for a game, or the highest points earners for a game. The game is targeted via its unique ID.

Available Parameters

Name Type Description Example
gameId Long The game ID you'd like to search for 14402
masters Int 1 for latest masters. 0 for non-master high scores. Defaults to 0. 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGameRankAndScore.Response, ErrorResponse> = api.getGameRankAndScore(
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val rankAndScore: GetGameRankAndScore.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetGame

A call to this endpoint will retrieve basic metadata about a game, targeted via its unique ID.

Available Parameters

Name Type Description Example
gameId Long The game ID you'd like to search for 14402

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGame.Response, ErrorResponse> = api.getGame(
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val game: GetGame.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Tickets

GetDeveloperTicketStats

A call to getTicketData() in this manner will retrieve ticket stats for a developer, targeted by that developer's site username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to retrieve ticket stats for xelnia

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetDeveloperTicketStats.Response, ErrorResponse> = api.getDeveloperTicketStats(
    username = "xelnia"
)

if (response is NetworkResponse.Success) {
    // handle the data
    val developerTicketStats: GetDeveloperTicketStats.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetAchievementTicketStats

A call to getTicketData() in this manner will retrieve ticket stats for an achievement, targeted by that achievement's unique ID.

Available Parameters

Name Type Description Example
achievementId Long The achievement ID you'd like to retrieve ticket stats for 12345

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetAchievementTicketStats.Response, ErrorResponse> = api.getAchievementTicketStats(
    achievementId = 12345
)

if (response is NetworkResponse.Success) {
    // handle the data
    val achievementTicketStats: GetAchievementTicketStats.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetGameTicketStats

A call to getTicketData() in this manner will retrieve the most recent ticket.

Available Parameters

Name Type Description Example
gameId Long The target game ID. 14402
shouldReturnTicketsList Int Set to 1 if you want deep ticket metadata in the response's Tickets array. 0
isGettingTicketsForUnofficialAchievements Int Set to 5 if you want ticket data for unofficial achievements. 0
count Int Count, number of records to return (default: 10, max: 100). 0
offset Int number of entries to skip (default: 0). 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGameTicketStats.Response, ErrorResponse> = api.getGameTicketStats(
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val gameTicketStats: GetGameTicketStats.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetMostRecentTickets

A call to getTicketData() in this manner will retrieve the most recent tickets

Available Parameters

Name Type Description Example
count Int Count, number of records to return (default: 10, max: 100). 10
offset Int number of entries to skip (default: 0). 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// you may pass an offset or count to its parameters
val response: NetworkResponse<GetMostRecentTickets.Response, ErrorResponse> = api.getMostRecentTickets()

if (response is NetworkResponse.Success) {
    // handle the data
    val tickets: GetMostRecentTickets.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetMostTicketedGames

A call to getTicketData() in this manner will retrieve the games on the site with the highest count of opened achievement tickets.

Available Parameters

Name Type Description Example
count Int number of records to return (default: 10, max: 100). 10
offset Int number of entries to skip (default: 0). 0
type Int Set to 5 if you want ticket data for unofficial achievements. 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetMostTicketedGames.Response, ErrorResponse> = api.getMostTicketedGames()

if (response is NetworkResponse.Success) {
    // handle the data
    val mostTicketedGames: GetMostTicketedGames.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetTicket (by ID)

A call to getTicketData() in this manner will retrieve ticket metadata information about a single achievement ticket, targeted by its ticket ID.

Available Parameters

Name Type Description Example
ticketId Int The ticket ID you'd like to query for 12345

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetTicketData.Response, ErrorResponse> = api.getTicket(
    ticketId = 12345
)

if (response is NetworkResponse.Success) {
    // handle the data
    val ticket: GetTicketData.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Users

GetAchievementsEarnedBetween

A call to this endpoint will retrieve a list of achievements unlocked by a given user between two given dates.

Available Parameters

Name Type Description Example
fromDate Date The starting date you'd like to query with 2022-01-01
toDate Date The ending date you'd like to query with 2022-01-08
username String The username of the user you'd like to query achievements for Jamiras

Example

// create dates
val dateFormat = SimpleDateFormat("yyyy-MM-dd")
val fromDate: Date = dateFormat.parse("2022-01-01")
val toDate: Date = dateFormat.parse("2022-01-08")

val response: NetworkResponse<GetUserRecentAchievements.Response, ErrorResponse> = api.getAchievementsEarnedBetween(
    username = "Jamiras",
    fromDate = fromDate,
    toDate = toDate
)

if (response is NetworkResponse.Success) {
    // handle the data
    val achievements: GetUserRecentAchievements.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetAchievementsEarnedOnDay

A call to this endpoint will retrieve a list of achievements unlocked by a given user on a specified date.

Available Parameters

Name Type Description Example
date Date The date of the day you'd like to query achievements at 2022-10-14
username String The username of the user you'd like to query achievements for Jamiras

Example

// create dates
val dateFormat = SimpleDateFormat("yyyy-MM-dd")
val date: Date = dateFormat.parse("2022-10-14")

val response: NetworkResponse<GetUserRecentAchievements.Response, ErrorResponse> = api.getAchievementsEarnedOnDay(
    username = "Jamiras",
    date = date
)

if (response is NetworkResponse.Success) {
    // handle the data
    val achievements: GetUserRecentAchievements.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserCompletedGames

A call to this endpoint will retrieve completion metadata about the games a given user has played. It returns two entries per each game: one for the softcore completion and one for the hardcore completion. These are designated by the hardcoreMode property on each completion object.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query completed games for MaxMilyin

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserCompletedGames.Response, ErrorResponse> = api.getUserCompletedGames(
    username = "MaxMilyin",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val completedGames: GetUserCompletedGames.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserCompletionProgress

A call to this endpoint will retrieve a giver user's completion progress, targeted by their username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query game progressions for MaxMilyin
maxRecords Int number of records to return (default: 100, max: 500). 100
offset Int Offset, number of entries to skip (default: 0). 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserCompletionProgress.Response, ErrorResponse> = api.getUserCompletionProgress(
    username = "MaxMilyin",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val completionProgress: GetUserCompletionProgress.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetGameInfoAndUserProgress

A call to this endpoint will retrieve extended metadata about a game, in addition to a user's progress about that game. This is targeted via a game's unique ID and a given username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query game progressions for. MaxMilyin
gameId Long The target game ID. 14402

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetGameInfoAndUserProgress.Response, ErrorResponse> = api.getGameInfoAndUserProgress(
    username = "MaxMilyin",
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val gameInfoAndUserProgress: GetGameInfoAndUserProgress.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserClaims

A call to this function will retrieve a list of achievement set claims made over the lifetime of a given user, targeted by their username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query claims for. MaxMilyin

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserClaims.Response, ErrorResponse> = api.getUserClaims(
    username = "Jamiras"
)

if (response is NetworkResponse.Success) {
    // handle the data
    val claims: GetUserClaims.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserGameRankAndScore

A call to this function will retrieve metadata about how a given user has performed/ranked on a given game, targeted by game ID.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query metadata for. MaxMilyin
gameId Long The target game ID. 14402

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserGameRankAndScore.Response, ErrorResponse> = api.getUserGameRankAndScore(
    username = "xelnia",
    gameId = 14402
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userGameRankAndScore: GetUserGameRankAndScore.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserPoints

A call to this function will retrieve a given user's hardcore and softcore points.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query points for. MaxMilyin

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserPoints.Response, ErrorResponse> = api.getUserPoints(
    username = "xelnia"
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userPoints: GetUserPoints.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserProgress

A call to this function will retrieve a given user's progress on a given list of games, targeted by game ID.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query points for. MaxMilyin
gameId String The target game ID. (separate list by ',' delimiter) 14402,1,2

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserProgress.Response, ErrorResponse> = api.getUserProgress(
    username = "xelnia",
    gameId = "1,14402"
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userProgress: GetUserProgress.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserRecentlyPlayedGames

A call to this function will retrieve a list of a target user's recently played games, via their username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query recently played gamed for. MaxMilyin
count Int number of records to return (default: 10, max: 50). 10
offset Int number of entries to skip (default: 0). 0

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserRecentlyPlayedGames.Response, ErrorResponse> = api.getUserRecentlyPlayedGames(
    username = "xelnia",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val recentlyPlayedGames: GetUserRecentlyPlayedGames.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserSummary

A call to this function will retrieve summary information about a given user, targeted by username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to query summary for. MaxMilyin

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserSummary.Response, ErrorResponse> = api.getUserSummary(
    username = "xelnia",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userProgress: GetUserSummary.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserProfile

A call to this endpoint will retrieve minimal user profile information, such as their ID, motto, most recent game ID, avatar, and points.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to get the profile of xelnia

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserProfile.Response, ErrorResponse> = api.getUserProfile(
    username = "xelnia",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val userProfile: GetUserProfile.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}
GetUserAwards

A call to this endpoint will retrieve metadata about the target user's site awards, via their username.

Available Parameters

Name Type Description Example
username String The username of the user you'd like to get metadata for xelnia

Example

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

val response: NetworkResponse<GetUserAwards.Response, ErrorResponse> = api.getUserAwards(
    username = "xelnia",
)

if (response is NetworkResponse.Success) {
    // handle the data
    val awards: GetUserAwards.Response = response.body

} else if (response is NetworkResponse.Error) {
    // if the server returns an error it be found here
    val errorResponse: ErrorResponse? = response.body

    // if the api (locally) had an internal error, it'll be found here
    val internalError: Throwable? = response.error
}

Testing

Apache maven must be correctly installed on the system.

To run tests for this project using Maven, execute the following command in your terminal:

mvn test

To compile the application, just run:

mvn clean package

Contributing

See Contribution Guidelines and Code of Conduct.

Security Vulnerabilities

Please review our security policy.

Credits

License

MIT License (MIT). See License File.