Skip to content

Commit c10cb0b

Browse files
gastongaidukgastongaiduk
authored
chore: add support to existing leaderboard APIs (#36)
1 parent e9f3175 commit c10cb0b

File tree

9 files changed

+408
-3
lines changed

9 files changed

+408
-3
lines changed

‎.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
/target/
2+
3+
.idea

‎README.md

Lines changed: 78 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ Then add this `api-kotlin` dependency to your `pom.xml` project!
2626
<dependency>
2727
<groupId>com.github.RetroAchievements</groupId>
2828
<artifactId>api-kotlin</artifactId>
29-
<version>1.0.10</version>
29+
<version>1.0.14</version>
3030
</dependency>
3131
```
3232

@@ -466,6 +466,82 @@ if (response is NetworkResponse.Success) {
466466

467467
</details>
468468

469+
<details>
470+
<summary>GetGameLeaderboards</summary>
471+
<br>
472+
473+
> A call to this endpoint will retrieve a given game's list of leaderboards, targeted by the game's ID.
474+
475+
**Available Parameters**
476+
477+
| Name | Type | Description | Example | Default |
478+
|:-------|:-----|:---------------------------------------|:--------|:--------|
479+
| gameId | Long | The target game ID. | 14402 | |
480+
| offset | Int | number of entries to skip | 100 | 0 |
481+
| count | Int | number of entries to return (max: 500) | 50 | 100 |
482+
483+
**Example**
484+
```kotlin
485+
val credentials = RetroCredentials("<username>", "<web api key>")
486+
val api: RetroInterface = RetroClient(credentials).api
487+
488+
val response: NetworkResponse<GetGameLeaderboards.Response, ErrorResponse> = api.getGameLeaderboards(
489+
gameId = 14402
490+
)
491+
492+
if (response is NetworkResponse.Success) {
493+
// handle the data
494+
val gameLeaderboards: GetGameLeaderboards.Response = response.body
495+
496+
} else if (response is NetworkResponse.Error) {
497+
// if the server returns an error it be found here
498+
val errorResponse: ErrorResponse? = response.body
499+
500+
// if the api (locally) had an internal error, it'll be found here
501+
val internalError: Throwable? = response.error
502+
}
503+
```
504+
505+
</details>
506+
507+
<details>
508+
<summary>GetLeaderboardEntries</summary>
509+
<br>
510+
511+
> A call to this endpoint will retrieve a given leaderboard's entries, targeted by its ID.
512+
513+
**Available Parameters**
514+
515+
| Name | Type | Description | Example | Default |
516+
|:-------|:-----|:---------------------------------------|:--------|:--------|
517+
| gameId | Long | The target game ID. | 14402 | |
518+
| offset | Int | number of entries to skip | 100 | 0 |
519+
| count | Int | number of entries to return (max: 500) | 50 | 100 |
520+
521+
**Example**
522+
```kotlin
523+
val credentials = RetroCredentials("<username>", "<web api key>")
524+
val api: RetroInterface = RetroClient(credentials).api
525+
526+
val response: NetworkResponse<GetLeaderboardEntries.Response, ErrorResponse> = api.getLeaderboardEntries(
527+
gameId = 14402
528+
)
529+
530+
if (response is NetworkResponse.Success) {
531+
// handle the data
532+
val leaderboardEntries: GetLeaderboardEntries.Response = response.body
533+
534+
} else if (response is NetworkResponse.Error) {
535+
// if the server returns an error it be found here
536+
val errorResponse: ErrorResponse? = response.body
537+
538+
// if the api (locally) had an internal error, it'll be found here
539+
val internalError: Throwable? = response.error
540+
}
541+
```
542+
543+
</details>
544+
469545
#### Tickets
470546

471547
<details>
@@ -554,7 +630,7 @@ if (response is NetworkResponse.Success) {
554630
| shouldReturnTicketsList | Int | Set to 1 if you want deep ticket metadata in the response's Tickets array. | 0 |
555631
| isGettingTicketsForUnofficialAchievements | Int | Set to 5 if you want ticket data for unofficial achievements. | 0 |
556632
| count | Int | Count, number of records to return (default: 10, max: 100). | 0 |
557-
| offset | Int | number of entries to skip (default: 0). | 0 |
633+
| offset | Int | number of entries to skip (default: 0). | 0 |
558634

559635
**Example**
560636
```kotlin

‎pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
<groupId>org.retroachievements</groupId>
88
<artifactId>api-kotlin</artifactId>
9-
<version>1.0.13</version>
9+
<version>1.0.14</version>
1010

1111
<dependencyManagement>
1212
<dependencies>

‎src/main/kotlin/org/retroachivements/api/RetroInterface.kt

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,28 @@ interface RetroInterface {
246246
@Query("t") masters: Int = 0
247247
): NetworkResponse<GetGameRankAndScore.Response, ErrorResponse>
248248

249+
/**
250+
* A call to this endpoint will retrieve a given game's list of leaderboards, targeted by the game's ID.
251+
*/
252+
@Mock @MockResponse(body = "/v1/game/GetGameLeaderboards.json")
253+
@POST("/API/API_GetGameLeaderboards.php")
254+
suspend fun getGameLeaderboards(
255+
@Query("i") gameId: Long,
256+
@Query("o") offset: Int = 0,
257+
@Query("c") count: Int = 100
258+
): NetworkResponse<GetGameLeaderboards.Response, ErrorResponse>
259+
260+
/**
261+
* A call to this endpoint will retrieve a given leaderboard's entries, targeted by its ID.
262+
*/
263+
@Mock @MockResponse(body = "/v1/game/GetLeaderboardEntries.json")
264+
@POST("/API/API_GetLeaderboardEntries.php")
265+
suspend fun getLeaderboardEntries(
266+
@Query("i") gameId: Long,
267+
@Query("o") offset: Int = 0,
268+
@Query("c") count: Int = 100
269+
): NetworkResponse<GetLeaderboardEntries.Response, ErrorResponse>
270+
249271
/**
250272
* A call to this endpoint will retrieve the complete list of all system ID and name pairs on the site.
251273
*

‎src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameLeaderboards.kt

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
package org.retroachivements.api.data.pojo.game
2+
3+
import com.google.gson.annotations.SerializedName
4+
5+
class GetGameLeaderboards {
6+
data class Response(
7+
@SerializedName("Count")
8+
val count: Long,
9+
@SerializedName("Total")
10+
val total: Long,
11+
@SerializedName("Results")
12+
val results: List<Leaderboard>,
13+
)
14+
15+
data class Leaderboard(
16+
@SerializedName("ID")
17+
val id: Long,
18+
@SerializedName("RankAsc")
19+
val rankAsc: Boolean,
20+
@SerializedName("Title")
21+
val title: String,
22+
@SerializedName("Description")
23+
val description: String,
24+
@SerializedName("Format")
25+
val format: String,
26+
@SerializedName("TopEntry")
27+
val topEntry: TopEntry,
28+
)
29+
30+
data class TopEntry(
31+
@SerializedName("User")
32+
val user: String,
33+
@SerializedName("Score")
34+
val score: Long,
35+
@SerializedName("FormattedScore")
36+
val formattedScore: String,
37+
)
38+
}

‎src/main/kotlin/org/retroachivements/api/data/pojo/game/GetLeaderboardEntries.kt

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
package org.retroachivements.api.data.pojo.game
2+
3+
import com.google.gson.annotations.SerializedName
4+
5+
class GetLeaderboardEntries {
6+
data class Response(
7+
@SerializedName("Count")
8+
val count: Long,
9+
@SerializedName("Total")
10+
val total: Long,
11+
@SerializedName("Results")
12+
val results: List<Entry>,
13+
)
14+
15+
data class Entry(
16+
@SerializedName("User")
17+
val user: String,
18+
@SerializedName("DateSubmitted")
19+
val dateSubmitted: String,
20+
@SerializedName("Score")
21+
val score: Long,
22+
@SerializedName("FormattedScore")
23+
val formattedScore: String,
24+
@SerializedName("Rank")
25+
val rank: Long,
26+
)
27+
28+
}

‎src/main/resources/mock/v1/game/GetGameLeaderboards.json

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
{
2+
"Count": 10,
3+
"Total": 64,
4+
"Results": [
5+
{
6+
"ID": 19062,
7+
"RankAsc": true,
8+
"Title": "New Zealand One",
9+
"Description": "Complete New Zealand S1 in least time",
10+
"Format": "MILLISECS",
11+
"TopEntry": {
12+
"User": "Thebpg13",
13+
"Score": 11903,
14+
"FormattedScore": "1:59.03"
15+
}
16+
},
17+
{
18+
"ID": 19063,
19+
"RankAsc": true,
20+
"Title": "New Zealand Two",
21+
"Description": "Complete New Zealand S2 in least time",
22+
"Format": "MILLISECS",
23+
"TopEntry": {
24+
"User": "Thebpg13",
25+
"Score": 15836,
26+
"FormattedScore": "2:38.36"
27+
}
28+
},
29+
{
30+
"ID": 19064,
31+
"RankAsc": true,
32+
"Title": "New Zealand Three",
33+
"Description": "Complete New Zealand S3 in least time",
34+
"Format": "MILLISECS",
35+
"TopEntry": {
36+
"User": "Thebpg13",
37+
"Score": 17619,
38+
"FormattedScore": "2:56.19"
39+
}
40+
},
41+
{
42+
"ID": 19065,
43+
"RankAsc": true,
44+
"Title": "New Zealand Four",
45+
"Description": "Complete New Zealand S4 in least time",
46+
"Format": "MILLISECS",
47+
"TopEntry": {
48+
"User": "Thebpg13",
49+
"Score": 14173,
50+
"FormattedScore": "2:21.73"
51+
}
52+
},
53+
{
54+
"ID": 19066,
55+
"RankAsc": true,
56+
"Title": "New Zealand Five",
57+
"Description": "Complete New Zealand S5 in least time",
58+
"Format": "MILLISECS",
59+
"TopEntry": {
60+
"User": "Thebpg13",
61+
"Score": 13963,
62+
"FormattedScore": "2:19.63"
63+
}
64+
},
65+
{
66+
"ID": 19067,
67+
"RankAsc": true,
68+
"Title": "New Zealand Six",
69+
"Description": "Complete New Zealand S6 in least time",
70+
"Format": "MILLISECS",
71+
"TopEntry": {
72+
"User": "JollyClubber",
73+
"Score": 15422,
74+
"FormattedScore": "2:34.22"
75+
}
76+
},
77+
{
78+
"ID": 19068,
79+
"RankAsc": true,
80+
"Title": "Greece One",
81+
"Description": "Complete Greece S1 in least time",
82+
"Format": "MILLISECS",
83+
"TopEntry": {
84+
"User": "Thebpg13",
85+
"Score": 15252,
86+
"FormattedScore": "2:32.52"
87+
}
88+
},
89+
{
90+
"ID": 19069,
91+
"RankAsc": true,
92+
"Title": "Greece Two",
93+
"Description": "Complete Greece S2 in least time",
94+
"Format": "MILLISECS",
95+
"TopEntry": {
96+
"User": "josef733",
97+
"Score": 13953,
98+
"FormattedScore": "2:19.53"
99+
}
100+
},
101+
{
102+
"ID": 19070,
103+
"RankAsc": true,
104+
"Title": "Greece Three",
105+
"Description": "Complete Greece S3 in least time",
106+
"Format": "MILLISECS",
107+
"TopEntry": {
108+
"User": "josef733",
109+
"Score": 12140,
110+
"FormattedScore": "2:01.40"
111+
}
112+
},
113+
{
114+
"ID": 19071,
115+
"RankAsc": true,
116+
"Title": "Greece Four",
117+
"Description": "Complete Greece S4 in least time",
118+
"Format": "MILLISECS",
119+
"TopEntry": {
120+
"User": "Thebpg13",
121+
"Score": 15219,
122+
"FormattedScore": "2:32.19"
123+
}
124+
}
125+
]
126+
}

0 commit comments

Comments
 (0)