Skip to content

Commit

Permalink
docs: add kotlin examples for @RetroAchievements/api-kotlin (#36)
Browse files Browse the repository at this point in the history
  • Loading branch information
@official-wizard
official-wizard authored Feb 26, 2024
1 parent 0020a64 commit aa092fc
Show file tree
Hide file tree
Showing 34 changed files with 901 additions and 138 deletions.
66 changes: 59 additions & 7 deletions docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,20 +27,55 @@ curl https://retroachievements.org/API/API_GetTopTenUsers.php?z=[your_username]&

## Quick Start (Client Library)

| Platform / Language | Repo |
| :------------------ | :------------------------------------------------------------------------ |
| NodeJS (JavaScript) | [`RetroAchievements/api-js`](https://github.com/RetroAchievements/api-js) |
| Platform / Language | Repo |
| :------------------ | :-------------------------------------------------------------------------------- |
| NodeJS (JavaScript) | [`RetroAchievements/api-js`](https://github.com/RetroAchievements/api-js) |
| JVM (Kotlin) | [`RetroAchievements/api-kotlin`](https://github.com/RetroAchievements/api-kotlin) |

Currently, our only official client library is for JavaScript/TypeScript/NodeJS. Additional client libraries will be added in the future for other tech stacks.
Currently, our official client libraries are for JavaScript/TypeScript/NodeJS and Kotlin.
Additional client libraries will be added in the future for other tech stacks and platforms.

To use our client library, you'll need to first install the package. Then, you'll create an authentication object. After these steps are completed, you are able to use any function provided by the library.
To use one of our client libraries, you'll need to first install the package corresponding to your tech stack.
Then, you'll create an authentication object.
After these steps are completed, you are able to use any function provided by the library.

::: code-group

```bash [NodeJS]
npm install --save @retroachievements/api
```

```xml [Kotlin + Maven]
<!-- add the jitpack.io repository to your `pom.xml` </repositories> -->
<repository>
<id>jitpack.io</id>
<url>https://www.jitpack.io</url>
</repository>

<!-- Then you'll be able to import the kotlin library by adding the following dependency to your `pom.xml` </dependencies> -->
<dependency>
<groupId>com.github.RetroAchievements</groupId>
<artifactId>api-kotlin</artifactId>
<version>1.0.1</version>
</dependency>
```

```groovy [Kotlin + Gradle]
// Add it in your root build.gradle at the end of repositories:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
// Add the dependency
dependencies {
implementation 'com.github.RetroAchievements:api-kotlin:1.0.1'
}
```

<!-- EXAMPLE OF HOW TO ADD OTHER PLATFORMS
```bash [PHP]
composer setup @retroachievements/api
Expand All @@ -51,7 +86,7 @@ composer setup @retroachievements/api

<br />

You can now create your authorization object using your web API key.
You can now create your authorization object using your RA username & web API key.

::: code-group

Expand All @@ -64,20 +99,37 @@ const webApiKey = "<your web API key>";
const authorization = buildAuthorization({ userName, webApiKey });
```

```kotlin [Kotlin]
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// access the api interface in `api`
```

:::

<br />

You now have all you need to use any function in the API. Each function takes this authorization object as its first argument. Here's an example:
You now have all you need to use any function in the API.
Here's a basic example of how to access the API:

::: code-group

```ts [NodeJS]
import { getGame } from "@retroachievements/api";

// Each function takes this authorization object as its first argument. Here's an example:
// This returns basic metadata about the game on this page:
// https://retroachievements.org/game/14402
const game = await getGame(authorization, { gameId: 14402 });
```

```kotlin [Kotlin]
// This returns basic metadata about the game on this page:
// https://retroachievements.org/game/14402
val response: NetworkResponse<GetGame.Response, ErrorResponse> = api.getGame(
gameId = 14402
)
```

:::
7 changes: 4 additions & 3 deletions docs/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ https://retroachievements.org/API/API_GetAchievementOfTheWeek.php?z=[your_userna

## Client Libraries

| Platform / Language | Repo |
| :------------------ | :------------------------------------------------------------------------ |
| NodeJS (JavaScript) | [`RetroAchievements/api-js`](https://github.com/RetroAchievements/api-js) |
| Platform / Language | Repo |
| :------------------ | :-------------------------------------------------------------------------------- |
| NodeJS (JavaScript) | [`RetroAchievements/api-js`](https://github.com/RetroAchievements/api-js) |
| JVM (Kotlin) | [`RetroAchievements/api-kotlin`](https://github.com/RetroAchievements/api-kotlin) |
30 changes: 26 additions & 4 deletions docs/v1/get-achievement-count.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,27 @@ const achievementCount = await getAchievementCount(authorization, {
});
```

```kotlin [Kotlin]
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
}
```

:::

## Response
Expand Down Expand Up @@ -78,7 +99,8 @@ const achievementCount = await getAchievementCount(authorization, {

## Source

| Repo | URL |
| :----------------------- | :-------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementCount.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/game/getAchievementCount.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementCount.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/game/getAchievementCount.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
31 changes: 27 additions & 4 deletions docs/v1/get-achievement-distribution.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,28 @@ const achievementDistribution = await getAchievementDistribution(
);
```

```kotlin [Kotlin]
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
}
```

:::

## Response
Expand Down Expand Up @@ -104,7 +126,8 @@ const achievementDistribution = await getAchievementDistribution(

## Source

| Repo | URL |
| :----------------------- | :--------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementDistribution.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/game/getAchievementDistribution.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementDistribution.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/game/getAchievementDistribution.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
28 changes: 24 additions & 4 deletions docs/v1/get-achievement-of-the-week.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,25 @@ const authorization = buildAuthorization({ userName, webApiKey });
const achievementOfTheWeek = await getAchievementOfTheWeek(authorization);
```

```kotlin [Kotlin]
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
}
```

:::

## Response
Expand Down Expand Up @@ -125,7 +144,8 @@ const achievementOfTheWeek = await getAchievementOfTheWeek(authorization);

## Source

| Repo | URL |
| :----------------------- | :------------------------------------------------------------------------------------------------ |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementOfTheWeek.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/feed/getAchievementOfTheWeek.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementOfTheWeek.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/feed/getAchievementOfTheWeek.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
30 changes: 26 additions & 4 deletions docs/v1/get-achievement-unlocks.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,27 @@ const achievementUnlocks = await getAchievementUnlocks(authorization, {
});
```

```kotlin [Kotlin]
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
}
```

:::

## Response
Expand Down Expand Up @@ -120,7 +141,8 @@ const achievementUnlocks = await getAchievementUnlocks(authorization, {

## Source

| Repo | URL |
| :----------------------- | :---------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementUnlocks.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/achievement/getAchievementUnlocks.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementUnlocks.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/achievement/getAchievementUnlocks.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
37 changes: 33 additions & 4 deletions docs/v1/get-achievements-earned-between.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,34 @@ const achievements = await getAchievementsEarnedBetween(authorization, {
});
```

```kotlin [Kotlin]
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// 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
}
```

:::

## Response
Expand Down Expand Up @@ -110,7 +138,8 @@ const achievements = await getAchievementsEarnedBetween(authorization, {

## Source

| Repo | URL |
| :----------------------- | :----------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedBetween.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedBetween.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedBetween.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedBetween.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
35 changes: 31 additions & 4 deletions docs/v1/get-achievements-earned-on-day.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,32 @@ const achievements = await getAchievementsEarnedOnDay(authorization, {
});
```

```kotlin [Kotlin]
val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// 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
}
```

:::

## Response
Expand Down Expand Up @@ -108,7 +134,8 @@ const achievements = await getAchievementsEarnedOnDay(authorization, {

## Source

| Repo | URL |
| :----------------------- | :--------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedOnDay.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedOnDay.ts |
| Repo | URL |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedOnDay.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedOnDay.ts |
| RetroAchievements/api-kotlin | https://github.com/RetroAchievements/api-kotlin/blob/main/src/main/kotlin/org/retroachivements/api/RetroInterface.kt |
Loading

0 comments on commit aa092fc

Please sign in to comment.