Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: modernize the remaining ticket data pages #33

Merged
merged 1 commit into from
Feb 25, 2024
Merged

docs: modernize the remaining ticket data pages #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 56 additions & 15 deletions docs/v1/tickets/get-developer-ticket-stats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,62 @@
<script setup>
import SampleRequest from '../../components/SampleRequest.vue';
</script>

# Get Developer Ticket Stats

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

[[toc]]

## HTTP Request

<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetTicketData?u=Hexadigital</SampleRequest>

### Query Parameters

| Name | Required? | Description |
| :--- | :-------- | :------------------------------- |
| `z` | Yes | Your username. |
| `y` | Yes | Your web API key. |
| `u` | Yes | The target developer's username. |

## Client Library

::: code-group

## Examples
```ts [NodeJS]
import { buildAuthorization, getTicketData } from "@retroachievements/api";

```ts
import { getTicketData } from "@retroachievements/api";
// First, build your authorization object.
const userName = "<your username on RA>";
const webApiKey = "<your web API key>";

const ticketStats = await getTicketData(authorization, { userName: "xelnia" });
const authorization = buildAuthorization({ userName, webApiKey });

// Then, make the API call.
const developerTicketStats = await getTicketData(authorization, {
userName: "Hexadigital",
});
```

## Returns
:::

## Response

::: code-group

```json [HTTP Response]
{
"User": "MockUser",
"Open": 0,
"Closed": 17,
"Resolved": 27,
"Total": 44,
"URL": "https://retroachievements.org/ticketmanager.php?u=MockUser"
}
```

```json
```json [NodeJS]
{
"user": "MockUser",
"open": 0,
Expand All @@ -23,14 +67,11 @@ const ticketStats = await getTicketData(authorization, { userName: "xelnia" });
}
```

## Parameters

| Name | Type | Description |
| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. |
| `userName` | `string` | The user to retrieve ticket stats for. |
:::

## Source

[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts)
[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php)
| Repo | URL |
| :----------------------- | :-------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts |
70 changes: 55 additions & 15 deletions docs/v1/tickets/get-game-ticket-stats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,61 @@
<script setup>
import SampleRequest from '../../components/SampleRequest.vue';
</script>

# Get Game Ticket Stats

A call to `getTicketData()` in this manner will retrieve ticket stats for a game, targeted by that game's unique ID.
A call to `API_GetTicketData` in this manner will retrieve ticket stats for a game, targeted by that game's unique ID.

[[toc]]

## HTTP Request

<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetTicketData?g=1</SampleRequest>

### Query Parameters

| Name | Required? | Description |
| :--- | :-------- | :--------------------------------------------------------------------------- |
| `z` | Yes | Your username. |
| `y` | Yes | Your web API key. |
| `g` | Yes | The target game ID. |
| `f` | | Set to 5 if you want ticket data for unofficial achievements. |
| `d` | | Set to 1 if you want deep ticket metadata in the response's `Tickets` array. |

## Client Library

::: code-group

## Examples
```ts [NodeJS]
import { buildAuthorization, getTicketData } from "@retroachievements/api";

```ts
import { getTicketData } from "@retroachievements/api";
// First, build your authorization object.
const userName = "<your username on RA>";
const webApiKey = "<your web API key>";

const ticketStats = await getTicketData(authorization, { gameId: 14402 });
const authorization = buildAuthorization({ userName, webApiKey });

// Then, make the API call.
const gameTicketStats = await getTicketData(authorization, { gameId: 1 });
```

## Returns
:::

## Response

::: code-group

```json [HTTP Response]
{
"GameID": 14402,
"GameTitle": "Dragster",
"ConsoleName": "Atari 2600",
"OpenTickets": 0,
"URL": "https://retroachievements.org/ticketmanager.php?g=14402"
}
```

```json
```json [NodeJS]
{
"gameId": 14402,
"gameTitle": "Dragster",
Expand All @@ -22,14 +65,11 @@ const ticketStats = await getTicketData(authorization, { gameId: 14402 });
}
```

## Parameters

| Name | Type | Description |
| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. |
| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. |
:::

## Source

[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts)
[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php)
| Repo | URL |
| :----------------------- | :-------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts |
124 changes: 77 additions & 47 deletions docs/v1/tickets/get-most-recent-tickets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,29 +1,86 @@
<script setup>
import SampleRequest from '../../components/SampleRequest.vue';
</script>

# Get Most Recent Tickets

A call to `getTicketData()` in this manner will retrieve ticket metadata information about the latest opened achievement tickets on RetroAchievements.
A call to `API_GetTicketData` in this manner will retrieve ticket metadata information about the latest opened achievement tickets on RetroAchievements.

## Examples
[[toc]]

```ts
import { getTicketData } from "@retroachievements/api";
## HTTP Request

const mostRecentTickets = await getTicketData(authorization);
```
<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetTicketData?o=0&c=10</SampleRequest>

```ts
const firstHundredTickets = await getTicketData(authorization, {
count: 100,
});
### Query Parameters

| Name | Required? | Description |
| :--- | :-------- | :---------------------------------------------------------- |
| `z` | Yes | Your username. |
| `y` | Yes | Your web API key. |
| `c` | | Count, number of records to return (default: 10, max: 100). |
| `o` | | Offset, number of entries to skip (default: 0). |

## Client Library

::: code-group

```ts [NodeJS]
import { buildAuthorization, getTicketData } from "@retroachievements/api";

const secondHundredTickets = await getTicketData(authorization, {
count: 100,
offset: 100,
// First, build your authorization object.
const userName = "<your username on RA>";
const webApiKey = "<your web API key>";

const authorization = buildAuthorization({ userName, webApiKey });

// Then, make the API call.
const mostRecentTickets = await getTicketData(authorization, {
count: 10,
offset: 0,
});
```

## Returns
:::

## Response

::: code-group

```json [HTTP Response]
{
"RecentTickets": [
{
"ID": 64866,
"AchievementID": 323665,
"AchievementTitle": "DEFAULT SETTINGS CHECK",
"AchievementDesc": "Normal or Hard difficulty, any character but \"Man\", any buster charge. All other settings OFF.",
"AchievementType": null,
"Points": 0,
"BadgeName": "361407",
"AchievementAuthor": "WCopeland",
"GameID": 24453,
"ConsoleName": "Mega Drive",
"GameTitle": "~Homebrew~ Mega Man: The Sequel Wars - Episode Red",
"GameIcon": "/Images/074329.png",
"ReportedAt": "2024-01-10 22:31:54",
"ReportType": 2,
"Hardcore": 1,
"ReportNotes": "asdfasdfasdfasdf\nRetroAchievements Hash: bff0eb90c2006edade14063d4a2d13cf\nEmulator: RALibRetro (123123)\nEmulator Version: 123",
"ReportedBy": "WCopeland",
"ResolvedAt": null,
"ResolvedBy": null,
"ReportState": 1,
"ReportStateDescription": "Open",
"ReportTypeDescription": "Did not trigger"
}
],
"OpenTickets": 1109,
"URL": "https://retroachievements.org/ticketmanager.php"
}
```

```json
```json [NodeJS]
{
"recentTickets": [
{
Expand All @@ -48,29 +105,6 @@ const secondHundredTickets = await getTicketData(authorization, {
"reportState": 1,
"reportStateDescription": "Open",
"reportTypeDescription": "Did not trigger"
},
{
"id": 56126,
"achievementId": 64753,
"achievementTitle": "Playing With a Handicap",
"achievementDesc": "Beat the easy CPU with the 'next piece' display off ",
"points": 10,
"badgeName": "68138",
"achievementAuthor": "Thoreau",
"gameId": 4939,
"consoleName": "Game Boy Color",
"gameTitle": "Tetris DX",
"gameIcon": "/Images/003696.png",
"reportedAt": "2023-02-03 20:08:49",
"reportType": 2,
"hardcore": true,
"reportNotes": "mockReportNotes",
"reportedBy": "TheJ5333",
"resolvedAt": null,
"resolvedBy": null,
"reportState": 1,
"reportStateDescription": "Open",
"reportTypeDescription": "Did not trigger"
}
// ...
],
Expand All @@ -79,15 +113,11 @@ const secondHundredTickets = await getTicketData(authorization, {
}
```

## Parameters

| Name | Type | Description |
| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- |
| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. |
| `count` | `number?` | Optional. How many recent tickets to fetch. The default is 10. The max is 100. |
| `offset` | `number?` | Optional. How many recent tickets to skip. Useful for pagination. Zero-indexed. The default is 0. |
:::

## Source

[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts)
[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php)
| Repo | URL |
| :----------------------- | :-------------------------------------------------------------------------------------- |
| RetroAchievements/RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php |
| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts |
Loading