The New Twitch API
Update: Please visit our Developer Forum post for more details regarding the deprecation of v3 and v5 of the Twitch API.
Twitch’s API gives developers the data they need to build tools for creators to grow their audiences. Today we’re announcing our brand new Twitch API, built with you, our developer community, in mind.
Why a new API?
The existing API was closely tied to Twitch’s website. Our developer community has built amazing tools using the platform but dealt with problems around reliability, unannounced breaking changes, onerous data access patterns (polling, anyone?), and inconsistency throughout. We could do better.
To tackle all of these challenges, we started with a blank slate rather than overhauling the existing API. A set of tenets drove our decision-making: simplicity, consistency, reliability, and transparency. With this in mind, as well as the feedback from the developer community, we designed the systems and data models to be easy to understand and easy to code with. We also created a public roadmap with clear messaging around upcoming changes so there are no more surprises or gotchas.
What are we building?
Our first release will provide a foundation for you to build tools for creators on Twitch. It will also give us an opportunity to gather your feedback and to ensure we’re moving in the right direction with the platform.
Creating a consistent experience
Because we want to provide a consistent experience with our API, we made some decisions that apply across the board:
All APIs will use a cursor for pagination. Once you understand pagination for one endpoint, you should understand it for all endpoints.
Parameters will always be in the query string. This will allow flexibility for us to support new functionality without changing the base route.
We will have bulk GET calls for our resources. You can request up to 100 users, streams, or other base resources. (Note: bulk calls are not available for specific relationships, such as whether or not user X follows user Y).
These are just some examples of the ways in which we’re listening to your feedback. We hope you enjoy discovering the rest!
Release stages
The ability to test out new APIs and systems is part of ensuring that we’re building the right thing for our community. Not all APIs and systems will go through these stages. We have to keep some surprises for you. :) With that in mind, we’ve aligned around three release stages. If you’re an AWS user, these are likely familiar to you.
Limited Preview — This stage is meant to be for testing out new ideas and gathering feedback from developers. The APIs in Limited Preview may never make it to the other stages. There are no SLA guarantees during this stage. Documentation will be minimal, and the data models can change drastically with short notice. APIs and systems in this stage should not be used in production applications.
Preview — This stage is meant for APIs and systems that are in release candidate shape. There will be fuller documentation and much less change than limited preview. This is the phase where items will be promoted to the public roadmap (more on that soon). This stage should not be used in production applications either.
General Availability — This is the fully released and supported stage. All systems are fully documented and meet our SLA. You can safely rely on these systems for your production applications.
Simplifying data models
When we looked at usage data, we saw that you find utility in a core set of resources (users, streams) and relationships (follows). It made sense for us to start there with the new API.
User and Channel objects had a large overlap in their data models, so we decided to reduce down to just a User object. This means that instead of a channel being an affiliate or partner, a user is an affiliate or partner. Similarly, the following relationship is between users inside the API. This type of relationship mapping is easier to understand for new developers and reflects our focus on community as a core experience at Twitch.
Streams will also be simplified. The data model will be revamped and made leaner, taking away extraneous data used to run the website. We focused on the data that is important for you as a developer — the user, the game, title, communities, and how they’re broadcasting (live, vodcast, or playlist).
Adding webhooks
One of the most common pieces of feedback we received around the API was that polling wasn’t fun. We agree. So, we’re also launching webhooks very soon! Our first webhook will be following, a commonly-polled endpoint. You simply subscribe to the following topic for a channel, and we’ll push you information when that user gets a new follower. It’s super fast. We’re going to be adding streams soon after, followed by subs and Bits in the months to come.
Reliability and transparency
Two guiding principles we’ve kept in mind while building the new Twitch API are reliability and transparency. For the team, these are exemplified by excellent performance, great uptime, insight into platform issues when they occur, and transparent change management. We’re approaching this in the following three ways.
1. Enforcing rate limiting to guarantee performance
First, to ensure excellent performance and great uptime, we’re enforcing rate limiting on the new API. Traditionally, we’ve provided guidance of 1 request per second but didn’t enforce in an automated way. We did a deep dive into our usage data and came to a number that we estimate would meet the needs of 87–92% of our existing developers — 2 requests per second. These rate limits are calculated in a 60-second window and your remaining rate limit will be returned to you in an HTTP header. We hope that webhooks provide a way to help you bring down API usage to make this an easy transition.
2. New status page for platform performance
Second, we want to be transparent about any issues with the API. In the past, you likely posted in the forums and waited for me to respond about an issue. That was obviously not a great experience, so we will ship a status page to give you real-time insight into the platform.
3. Public roadmap
Third, a common question we get is, “When are you going to implement…” and the common answer is, “We don’t comment on future features of the platform.” Instead of that, we have a public roadmap that shows exactly what we’re working on and what we’re thinking about adding. Check it out at dev.twitch.tv/roadmap and let us know what you’d like to see us add to the new Twitch API.
Access to new metadata
We’ve recently begun building features based on real-time video metadata generated through computer vision and machine learning that analyzes and categorizes live streams. We used this data to add new filters to the Overwatch and Hearthstone directory pages that let viewers browse channels based on the in-game action, and now we want to see what our developer community can do! The first version of the Deep Metadata API will be publicly available in Limited Preview as part of the streams object. You will be able to use the API to identify the Hero a streamer is playing in Overwatch or the streamer’s Hero Class and Game Mode in Hearthstone.
In closing
When I initially pitched the new Twitch API, the first sentence I typed was, “This is our love letter to developers.” In everything we add to the platform, we want to ensure that our community of developers are represented and that you have a great experience building for creators. We hope you enjoy all of these updates and can’t wait to see what you build!