Skip to content

Commit

Permalink
docs: update helix endpoint methods
Browse files Browse the repository at this point in the history
  • Loading branch information
@iProdigy
iProdigy committed Jan 24, 2024
1 parent bbfcd7c commit b3e0e97
Show file tree
Hide file tree
Showing 25 changed files with 206 additions and 151 deletions.
18 changes: 9 additions & 9 deletions docs/versioned_docs/version-1.x/rest-helix/analytics-extension-url.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,18 +29,18 @@ HystrixCommand<ExtensionAnalyticsList> getExtensionAnalyticUrl(

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| authToken | string | User Auth Token |
| authToken | string | User Access Token with the `analytics:read:extensions` scope. |

*Optional Parameters*

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without `extension_id`. If an `extension_id` is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
| first | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
| type | string | Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s Extensions. Limit: 1. Valid values: "overview_v1", "overview_v2". Default: all report types for the authenticated user’s Extensions. |
| extension_id | string | Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s extensions. |
| started_at | string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. This must be on or after January 31, 2018.<br /><br />If this is provided, `ended_at` also must be specified. If `started_at` is earlier than the default start date, the default date is used. Default: January 31, 2018 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day. |
| ended_at | string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. The report covers the entire ending date; e.g., if `2018-05-01T00:00:00Z` is specified, the report covers up to `2018-05-01T23:59:59Z`. <br /><br />If this is provided, `started_at` also must be specified. If `ended_at` is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |
| Name | Type | Description |
| ------------ |:---------:| -----------:|
| after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without `extension_id`. If an `extension_id` is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
| limit | integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
| type | string | The type of analytics report to get. Possible values are: "overview_v2". |
| extension_id | string | Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s extensions. |
| started_at | string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. This must be on or after January 31, 2018.<br /><br />If this is provided, `ended_at` also must be specified. If `started_at` is earlier than the default start date, the default date is used. Default: January 31, 2018 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day. |
| ended_at | string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. The report covers the entire ending date; e.g., if `2018-05-01T00:00:00Z` is specified, the report covers up to `2018-05-01T23:59:59Z`. <br /><br />If this is provided, `started_at` also must be specified. If `ended_at` is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |

## Code-Snippets

Expand Down
24 changes: 12 additions & 12 deletions docs/versioned_docs/version-1.x/rest-helix/analytics-game-url.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ HystrixCommand<GameAnalyticsList> getGameAnalyticUrl(
@Param("token") String authToken,
@Param("after") String after,
@Param("first") Integer limit,
@Param("game_id") Long gameId,
@Param("game_id") String gameId,
@Param("type") String type,
@Param("started_at") String startedAt,
@Param("ended_at") String endedAt
Expand All @@ -29,20 +29,20 @@ HystrixCommand<GameAnalyticsList> getGameAnalyticUrl(

*Required Parameters*

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| authToken | string | User Auth Token |
| Name | Type | Description |
| --------- |:---------:|------------:|
| authToken | string | User Access Token with the `analytics:read:games` scope. |

*Optional Parameters*

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without `extension_id`. If an `extension_id` is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
| first | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
| type | string | Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s Extensions. Limit: 1. Valid values: "overview_v1", "overview_v2". Default: all report types for the authenticated user’s Extensions. |
| extension_id | string | Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension. If this is not specified, the response includes multiple URLs (paginated), pointing to separate analytics reports for each of the authenticated user’s extensions. |
| started_at | string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. This must be on or after January 31, 2018.<br /><br />If this is provided, `ended_at` also must be specified. If `started_at` is earlier than the default start date, the default date is used. Default: January 31, 2018 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day. |
| ended_at | string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. The report covers the entire ending date; e.g., if `2018-05-01T00:00:00Z` is specified, the report covers up to `2018-05-01T23:59:59Z`. <br /><br />If this is provided, `started_at` also must be specified. If `ended_at` is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |
| Name | Type | Description |
| ---------- |:---------:| -----------:|
| after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without `extension_id`. If an `extension_id` is specified, it supersedes any cursor/offset combinations. The cursor value specified here is from the pagination response field of a prior query. |
| limit | integer | Maximum number of objects to return. Maximum: 100. Default: 20. |
| game_id | string | The game’s client ID. If specified, the response contains a report for the specified game. If not specified, the response includes a report for each of the authenticated user’s games. |
| type | string | The type of analytics report to get. Possible values are: "overview_v2". |
| started_at | string | Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. This must be on or after January 31, 2018.<br /><br />If this is provided, `ended_at` also must be specified. If `started_at` is earlier than the default start date, the default date is used. Default: January 31, 2018 (overview_v2) or 90 days (overview_v1) before the report was issued. The file contains one row of data per day. |
| ended_at | string | Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: `YYYY-MM-DDT00:00:00Z`. The report covers the entire ending date; e.g., if `2018-05-01T00:00:00Z` is specified, the report covers up to `2018-05-01T23:59:59Z`. <br /><br />If this is provided, `started_at` also must be specified. If `ended_at` is later than the default end date, the default date is used. Default: 1-2 days before the request was issued (depending on report availability). |

## Code-Snippets

Expand Down
6 changes: 3 additions & 3 deletions docs/versioned_docs/version-1.x/rest-helix/bits-leaderboard.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,10 +18,10 @@ Gets a ranked list of Bits leaderboard information for an authorized broadcaster
@Headers("Authorization: Bearer {token}")
HystrixCommand<BitsLeaderboard> getBitsLeaderboard(
@Param("token") String authToken,
@Param("count") String count,
@Param("count") Integer count,
@Param("period") String period,
@Param("started_at") String startedAt,
@Param("user_id") Long userId
@Param("user_id") String userId
);
```

Expand All @@ -35,7 +35,7 @@ HystrixCommand<BitsLeaderboard> getBitsLeaderboard(

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| count | string | Number of results to be returned. Maximum: 100. Default: 10. |
| count | integer | Number of results to be returned. Maximum: 100. Default: 10. |
| period | string | Time period over which data is aggregated (PST time zone). This parameter interacts with `started_at`. Valid values are given below. Default: `"all"`.<br /><br />"day" – 00:00:00 on the day specified in started_at, through 00:00:00 on the following day.<br />"week" – 00:00:00 on Monday of the week specified in started_at, through 00:00:00 on the following Monday.<br />"month" – 00:00:00 on the first day of the month specified in started_at, through 00:00:00 on the first day of the following month.<br />"year" – 00:00:00 on the first day of the year specified in started_at, through 00:00:00 on the first day of the following year.<br />"all" – The lifetime of the broadcaster's channel. If this is specified (or used by default), started_at is ignored. |
| started_at | string | Timestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if period is "all".<br /><br />Any + operator should be URL encoded.<br /><br />Currently, the HH:MM:SS part of this value is used only to identify a given day in PST and otherwise ignored. For example, if the started_at value resolves to 5PM PST yesterday and period is "day", data is returned for all of yesterday. |
| user_id | string | ID of the user whose results are returned; i.e., the person who paid for the Bits.<br/>As long as count is greater than 1, the returned data includes additional users, with Bits amounts above and below the user specified by user_id.<br />If user_id is not provided, the endpoint returns the Bits leaderboard data across top users (subject to the value of count). |
Expand Down
10 changes: 2 additions & 8 deletions docs/versioned_docs/version-1.x/rest-helix/clips-create.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,6 @@ Creates a clip programmatically. This returns both an ID and an edit URL for the

Clip creation takes time. We recommend that you query Get Clips, with the clip ID that is returned here. If Get Clips returns a valid clip, your clip creation was successful. If, after 15 seconds, you still have not gotten back a valid clip from Get Clips, assume that the clip was not created and retry Create Clip.

This endpoint has a global rate limit, across all callers. The limit may change over time, but the response includes informative headers:

```
Ratelimit-Helixclipscreation-Limit: <int value>
Ratelimit-Helixclipscreation-Remaining: <int value>
```

## Method Definition

Expand All @@ -37,13 +31,13 @@ HystrixCommand<CreateClipList> createClip(
| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| authToken | string | User Auth Token |
| broadcaster_id | string | ID of the stream from which the clip will be made. |

*Optional Query String Parameters*

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| broadcaster_id | string | ID of the stream from which the clip will be made. |
| has_delay | string | If `false`, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream). Default: `false`. |
| has_delay | boolean | If `false`, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream). Default: `false`. |

## Code-Snippets

Expand Down
30 changes: 16 additions & 14 deletions docs/versioned_docs/version-1.x/rest-helix/clips-get.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,19 @@ The response has a JSON payload with a `data` field containing an array of clip
## Method Definition

```java
@RequestLine("GET /clips?broadcaster_id={broadcaster_id}&game_id={game_id}&id={id}&after={after}&before={before}&first={first}&started_at={started_at}&ended_at={ended_at}")
@RequestLine("GET /clips?broadcaster_id={broadcaster_id}&game_id={game_id}&id={id}&after={after}&before={before}&first={first}&started_at={started_at}&ended_at={ended_at}&is_featured={is_featured}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ClipList> getClips(
@Param("token") String authToken,
@Param("broadcaster_id") Long broadcasterId,
@Param("game_id") String gameId,
@Param("id") String id,
@Param("after") String after,
@Param("before") String before,
@Param("first") Integer limit,
@Param("started_at") Date startedAt,
@Param("ended_at") Date endedAt
@Param("broadcaster_id") String broadcasterId,
@Param("game_id") String gameId,
@Param("id") List<String> ids,
@Param("after") String after,
@Param("before") String before,
@Param("first") Integer limit,
@Param("started_at") Instant startedAt,
@Param("ended_at") Instant endedAt,
@Param("is_featured") Boolean isFeatured
);
```

Expand All @@ -43,12 +44,13 @@ HystrixCommand<ClipList> getClips(

| Name | Type | Description |
| ------------- |:---------:| -----------------:|
| authToken | string | User Auth Token |
| authToken | string | User or App Access Token (or null if authentication was passed to the module builder). |
| after | string | Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query. |
| before | string | Cursor for backward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries specifying broadcaster_id or game_id. The cursor value specified here is from the pagination response field of a prior query. |
| first | string | Maximum number of objects to return. Maximum: 100. Default: 20. |
| limit | integer| Maximum number of objects to return. Maximum: 100. Default: 20. |
| started_at | string | Starting date/time for returned clips, in RFC3339 format. (Note that the seconds value is ignored.) If this is specified, ended_at also should be specified; otherwise, the ended_at date/time will be 1 week after the started_at value. |
| ended_at | string | Ending date/time for returned clips, in RFC3339 format. (Note that the seconds value is ignored.) If this is specified, started_at also must be specified; otherwise, the time period is ignored. |
| is_featured | boolean | Whether the response includes featured clips. If true, returns only clips that are featured. If false, returns only clips that aren’t featured. All clips are returned if this parameter is not specified. |

## Code-Snippets

Expand All @@ -58,7 +60,7 @@ HystrixCommand<ClipList> getClips(
<TabItem value="java" label="Java">

```java
ClipList clipList = twitchClient.getHelix().getClips(null, "488552", null, null, null, null, null, null).execute();
ClipList clipList = twitchClient.getHelix().getClips(null, "488552", null, null, null, null, null, null, null, null).execute();
clipList.getData().forEach(clip -> {
System.out.println("Found Clip: " + clip.getId());
});
Expand All @@ -68,7 +70,7 @@ clipList.getData().forEach(clip -> {
<TabItem value="kotlin" label="Kotlin">

```kotlin
val clipList = twitchClient.helix.getClips(null, "488552", null, null, null, null, null, null).execute();
val clipList = twitchClient.helix.getClips(null, "488552", null, null, null, null, null, null, null, null).execute();
clipList.`data`.forEach { clip ->
println("Found Clip: ${clip.id}")
}
Expand All @@ -78,7 +80,7 @@ clipList.`data`.forEach { clip ->
<TabItem value="groovy" label="Groovy">

```groovy
def clipList = twitchClient.helix.getClips(null, "488552", null, null, null, null, null, null).execute();
def clipList = twitchClient.helix.getClips(null, "488552", null, null, null, null, null, null, null, null).execute();
clipList.data.each { clip ->
System.out.println "Found Clip: ${clip.id}"
}
Expand Down
2 changes: 1 addition & 1 deletion docs/versioned_docs/version-1.x/rest-helix/drops-get-entitlements.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ HystrixCommand<DropsEntitlementList> getDropsEntitlements(
| id | string | Unique identifier of the entitlements |
| user_id | string | User ID, that was granted entitlements |
| game_id | string | Game ID, that offered entitlements |
| fulfillment_status | string | Status used to filter entitlements. Example- 'claimed' or 'fulfilled' |
| fulfillment_status | enum | Status used to filter entitlements. Example- 'claimed' or 'fulfilled' |
| after | string | The cursor used to get the next page of results. |
| first | integer | The maximum number of entitlements to return per page in the response. |

Expand Down
6 changes: 6 additions & 0 deletions docs/versioned_docs/version-1.x/rest-helix/entitlements-codes.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,16 @@ import TabItem from '@theme/TabItem';

Gets the status of one or more provided codes.

:::warning

Twitch decommissioned this endpoint on 2023-02-27.

:::

## Method Definition

```java
@Deprecated
@RequestLine("GET /entitlements/codes?code={code}&user_id={user_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CodeStatusList> getCodeStatus(
Expand Down
Loading

0 comments on commit b3e0e97

Please sign in to comment.