|
| 1 | +# mock-api |
| 2 | + |
| 3 | +- [mock-api](#mock-api) |
| 4 | + - [Description](#description) |
| 5 | + - [generate](#generate) |
| 6 | + - [start](#start) |
| 7 | + - [mock namespace](#mock-namespace) |
| 8 | + - [units namespace](#units-namespace) |
| 9 | + - [auth namespace](#auth-namespace) |
| 10 | + |
| 11 | +## Description |
| 12 | + |
| 13 | +The `mock-api` product has two primary functions. The first is to generate so-called `units`- those are core building blocks on Twitch. These are, for now: |
| 14 | + |
| 15 | +* Application Clients |
| 16 | +* Categories |
| 17 | +* Streams |
| 18 | +* Subscriptions |
| 19 | +* Tags |
| 20 | +* Teams |
| 21 | +* Users |
| 22 | + |
| 23 | +The second is the actual server used to mock the endpoints. In the next iteration, you will be able to edit these and add further ones manually (for example, making a user with specific attributes), but for the beta we won't be providing this functionality as the current `generate` feature will make all of these (and more), |
| 24 | + |
| 25 | + |
| 26 | +## generate |
| 27 | + |
| 28 | +This command will generate a specified number of users with associated relationships (e.g. subscriptions/mods/blocks). |
| 29 | + |
| 30 | +**Args** |
| 31 | + |
| 32 | +None. |
| 33 | + |
| 34 | +**Flags** |
| 35 | + |
| 36 | +| Flag | Shorthand | Description | Example | Required? (Y/N) | |
| 37 | +|-----------|-----------|-----------------------------------------------------------------------------|---------|-----------------| |
| 38 | +| `--count` | `-c` | Number of users to generate (and associated relationships). Defaults to 10. | `-c 25` | N | |
| 39 | + |
| 40 | + |
| 41 | +## start |
| 42 | + |
| 43 | +The `start` function starts a new mock server for use with testing functionality. Currently, this replicates a large majority of the current API endpoints on the new API, but are ommitting: |
| 44 | + |
| 45 | +* GET /analytics/extensions |
| 46 | +* GET /analytics/games |
| 47 | +* GET /extensions/transactions |
| 48 | +* POST /eventsub/subscriptions |
| 49 | +* DELETE /eventsub/subscriptions |
| 50 | +* GET /eventsub/subscriptions |
| 51 | +* GET /users/extensions/list |
| 52 | +* GET /users/extensions |
| 53 | +* PUT /users/extensions |
| 54 | +* GET /webhooks/subscriptions |
| 55 | + |
| 56 | +For many of these, we are exploring how to better integrate this with existing features (for example, allowing events to be triggered on unit creation or otherwise), and for others, the value is minimal compared to the docs. All other endpoints should be currently supported, however it is possible to be out of date- if so, [please raise an issue](https://github.com/twitchdev/twitch-cli/issues). |
| 57 | + |
| 58 | +To access these endpoints, you will point your code to `http://localhost:<port>/mock`, where port is either the default port (8080) or one you specified using the flag. For example, to access the users endpoint: |
| 59 | + |
| 60 | +```sh |
| 61 | +curl -i -H "Accept: application/json" http://localhost:8080/mock/users |
| 62 | +``` |
| 63 | + |
| 64 | +For information on accessing those endpoints, please see [the documentation on the Developer site](https://dev.twitch.tv/docs/api/reference). |
| 65 | + |
| 66 | +In total, there are three namespaces (top-level folder) that are used: |
| 67 | + |
| 68 | +### mock namespace |
| 69 | + |
| 70 | +Example URL: `http://localhost:8080/mock/users` |
| 71 | + |
| 72 | +This namespace houses all mock endpoints. For information on accessing those endpoints, please see [the documentation on the Developer site](https://dev.twitch.tv/docs/api/reference). |
| 73 | + |
| 74 | +### units namespace |
| 75 | + |
| 76 | +Example URL: `http://localhost:8080/units/users` |
| 77 | + |
| 78 | +This endpoint gives an unauthenticated peek into the list of units in the database- used for debugging or finding units for testing. Endpoints include: |
| 79 | + |
| 80 | +* GET /categories |
| 81 | +* GET /clients |
| 82 | +* GET /streams |
| 83 | +* GET /subscriptions |
| 84 | +* GET /tags |
| 85 | +* GET /teams |
| 86 | +* GET /users |
| 87 | +* GET /videos |
| 88 | + |
| 89 | +More will be added in the future. |
| 90 | + |
| 91 | +### auth namespace |
| 92 | + |
| 93 | +This endpoint is a light implementation of OAuth, without support for OIDC. These endpoints are used to generate either an app access token or user token. The two endpoints are below, with documentation and examples using cURL. All tokens expire after 24 hours. |
| 94 | + |
| 95 | +**POST /authorize** |
| 96 | + |
| 97 | +This endpoint generates a user token, similar to OAuth authorization code. |
| 98 | + |
| 99 | +| Query Parameter | Description | Example | Required? (Y/N) | |
| 100 | +|-----------------|----------------------------------------------------------------------|--------------------------|-----------------| |
| 101 | +| `client_id` | Application client ID, which is output by the `generate` command. | `?client_id=1234` | Y | |
| 102 | +| `client_secret` | Application client secret, which is output by the `generate` command | `?client_secret=1234` | Y | |
| 103 | +| `grant_type` | Must be `user_token` | `?grant_type=user_token` | Y | |
| 104 | +| `user_id` | User to get the token for. | `?user_id=1234` | Y | |
| 105 | +| `scope` | Space seperated list of scopes to request for the given user. | `?scope=bits:read` | N | |
| 106 | + |
| 107 | +The response is identical to the OAuth `authorization_code` with the omission of a refresh token. |
| 108 | + |
| 109 | +Example request for user 78910 with no scopes: |
| 110 | + |
| 111 | +```sh |
| 112 | +curl -X POST http://localhost:8080/auth/authorize?client_id=123&client_secret=456&grant_type=user_token&user_id=78910 |
| 113 | +``` |
| 114 | + |
| 115 | +Example response: |
| 116 | + |
| 117 | +```json |
| 118 | +{ |
| 119 | + "access_token": "ff4231a5befca12", |
| 120 | + "refresh_token": "", |
| 121 | + "expires_in": 86399, |
| 122 | + "scope": [], |
| 123 | + "token_type": "bearer" |
| 124 | +} |
| 125 | +``` |
| 126 | + |
| 127 | +Docs: https://dev.twitch.tv/docs/authentication/getting-tokens-oauth#oauth-authorization-code-flow |
| 128 | + |
| 129 | +**POST /token** |
| 130 | + |
| 131 | +This endpoint generates an app access token using the `client_credentials` flow as documented. |
| 132 | + |
| 133 | + |
| 134 | +| Query Parameter | Description | Example | Required? (Y/N) | |
| 135 | +|-----------------|----------------------------------------------------------------------|--------------------------|-----------------| |
| 136 | +| `client_id` | Application client ID, which is output by the `generate` command. | `?client_id=1234` | Y | |
| 137 | +| `client_secret` | Application client secret, which is output by the `generate` command | `?client_secret=1234` | Y | |
| 138 | +| `grant_type` | Must be `client_credentials` | `?grant_type=user_token` | Y | |
| 139 | +| `scope` | Space seperated list of scopes to request for the given user. | `?scope=bits:read` | N | |
| 140 | + |
| 141 | + |
| 142 | +The response is identical to the OAuth `client_credentials` flow with the omission of a refresh token. |
| 143 | + |
| 144 | +Example request with no scopes: |
| 145 | + |
| 146 | +```sh |
| 147 | +curl -X POST http://localhost:8080/auth/token?client_id=123&client_secret=456&grant_type=client_credentials |
| 148 | +``` |
| 149 | + |
| 150 | +Example response: |
| 151 | + |
| 152 | +```json |
| 153 | +{ |
| 154 | + "access_token": "4f5dce6cea626cb", |
| 155 | + "refresh_token": "", |
| 156 | + "expires_in": 86399, |
| 157 | + "scope": [], |
| 158 | + "token_type": "bearer" |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +Docs: https://dev.twitch.tv/docs/authentication/getting-tokens-oauth#oauth-client-credentials-flow |
| 163 | + |
| 164 | +**Args** |
| 165 | + |
| 166 | +None. |
| 167 | + |
| 168 | +**Flags** |
| 169 | + |
| 170 | +| Flag | Shorthand | Description | Example | Required? (Y/N) | |
| 171 | +|----------|-----------|------------------------------------------|-----------|-----------------| |
| 172 | +| `--port` | `-p` | Port number to use with the mock server. | `-p 8000` | N | |
| 173 | + |
| 174 | + |
0 commit comments