Summary
The Twitch CLI has been designed with the mission that it should empower developers to easily test and simulate the Twitch APIs, whether that’s EventSub, WebSub, or by directly calling the Twitch API via command line.
We’ve seen the community take to the CLI better than we could’ve imagined, and we’re looking to add a full mock API implementation into the CLI.
Motivation
We’ve heard consistently that developers would like to test against the Twitch API without requiring affiliate/partner accounts. The most recent examples coming from the Channel Points hackathon, as that API requires the use of an affiliate account to test the creation and redemption of events.
Consistency with production is the most important factor when using it; developing/testing against a mock API that doesn’t match expected production results is a frustrating experience as a developer.
With that in mind, we believe the CLI is the best place for this mock implementation for a few reasons:
- It can be run offline/disconnected from the broader web, allowing users to develop on limited internet connections or used in CI/CD tooling
- It allows us to keep it simple and give an individual a sandbox to operate in without requiring shared resources
Proposed Solution
The CLI will be able to fully mock all Twitch API endpoints, including subscriptions and channel points.
As stated, we will fully implement all current Twitch API endpoints, along with matched production constraints (e.g. must provide a broadcaster_id for some endpoints).
These endpoints will be hosted locally via a local webserver and follow identical paths to allow for easy replacement within client libraries to enable easier development against. As this is a reimplementation of a currently-available API, there will be no major changes other than the ones covered below.
The CLI will allow developers to create fake users, subscriptions, and other principles for use with the APIs.
To allow developers to effectively use the mock endpoints, in addition to the public endpoints offered, we will also allow developers to create “principles”, or important constructs for use within the API. For example, you could recreate a user locally as a way to develop with specific users in mind. Additionally, we’ll provide methods to create faked subscriptions (and other monetary events) to be able to use in fetching later.
Detailed Changes
Authorization
For the initial implementation of this feature, authorization will fall out of scope for a local-only mock API. What this means is that the CLI will check for the existence of both the Client ID and Bearer token, but not confirm validity, scopes, or matching client IDs.
Mock API Implementation
Beyond authorization changes, the API will map to the Twitch API as close as possible without requiring an internet connection. Each endpoint will follow the same naming conventions, including parameters.
In the future, we will automate the drift between the CLI and production API to avoid discrepancies.
CRUD APIs for Principles
As noted above, one of the other portions of the mock API featureset will include the ability to manually create specific items. This will look like:
POST https://localhost:3000/api/user
-- Request Body --
{
“user_id”: “1234”,
“user_login”:”concreteentree”,
“user_name”:”ConcreteEntree”,
}
-- Response Code --
204
For each of the endpoints, there will be supplied documentation within the CLI docs, as well as helpful error messaging to provide information on how to fix the issue.
WIth these APIs, they’ll be written to the existing SQLite database for use with further principles/calls. For example, if you were to call Get Subscriptions for the above user_id, it would return an empty array until you create a subscription for the example user.
FAQ
Will the mock API be a true 1:1 implementation of the Twitch API?
Not exactly, but close. The major caveat will be around Authorization, discussed above.
Why? Simply put, this would require one of two things; the first would be an internet connection to check against the production OAuth endpoints. Given this is against the spirit of the functionality, it doesn’t feel like a good fit. The second would be a reimplementation of the OAuth flows (or some mock implementation thereof), which could cause feature bloat and confusion on how OAuth works in production.
As a result, this is simply allowing you to mock out the responses from the API and test that your code is working properly so long as you get data.
at 1:35!! We can’t speak for other - maybe less developed - places, but if every Twitch developer is also a Twitch streamer or broadcaster, slow internet is going to be a big problem in the first place. Does the mock really need to address this problem?