Change in access to deprecated Kraken Twitch APIs

[mauerbac]

August 15th, 2019 - How do you know that you’re accessing Twitch’s v5 API correctly? You must pass the application/vnd.twitchtv.v5+json in an “Accept” header for your requests to access v5. Otherwise your request will receive a 410 response code once v3 is no longer available.

Here is an example for correctly passing the header:

Note that there will no longer be a default version of Kraken namespace of Twitch APIs on September 12th, 2019. All functionality under the Kraken namespace has been deprecated and unsupported as of 2016, and will be withdrawn completely over the course of 2019-2020.

We understand that for developers removing a default version of the Kraken API may feel like a change in accessibility to the Twitch API. We made this change to ensure a more consistent experience with Kraken (i.e v5) and its associated documentation. The former default Kraken API (i.e. v3), will be withdrawn completely in September 2019.

Our commitment to developers is to build the tools and services they need to build amazing experiences on Twitch. When it comes to the Twitch API offering, we recognize that supporting multiple versions simultaneously makes building on Twitch challenging for developers. While well-intentioned, building out several versions of the API has created a fragmented API experience that slows development. We know we can deliver a better experience, and are working diligently towards a solution. Our aim for 2019 is to consolidate all supported API functionality under the Helix namespace of the Twitch API.

Thank you for being a valued member of the Twitch Developer community. This change is part of our continued effort to improve developer products which enable creators like yourself to deliver the interactive experiences that make Twitch what it is today.

[Elyot_Grant]

Hello,

Elyot Grant here, founder of Lunarch Studios and lead developer of Prismata, which has been using the twitch API for almost 4 years now.

This change is a huge problem for us. And I’m actually very upset that it wasn’t communicated to us in any fashion at all. We read through all of the API migration guides when you first sent us the email, and we were assured that everything would be fine: https://media.discordapp.net/attachments/403407224610750465/613828755281936397/unknown.png

Then you SILENTLY, WITHOUT TELLING US, COMPLETELY DECIDE TO BREAK IT!? And remove all trace of the backward compatibility from your documentation? Why…? Our twitch API integration just completely stopped working a few hours ago. And it will be broken again tomorrow, in our live product. What the hell?

In any case, we rely on client side API calls through Adobe AIR, which does not support non-default headers for GET requests because we’re not running the requests from an application security sandbox. We can’t add the Accept header, it literally gives a runtime error.

Error #2096: The HTTP request header Accept: cannot be set via ActionScript.

Do you have a solution for this? If not, can you please revert the headerless behaviour, or provide another way for us to get information about the live streams available right now (e.g. could you allow us to specify the version as a URL parameter rather than a header? You already support this with the client_id parameter.)

I just want a direct one-URL solution like this: https://api.twitch.tv/kraken/streams?client_id=ip6bsskfxjqyh0vdswgiop7vt6pm022&game=prismata

If I have to add the version in there somewhere, it’s fine. But I can’t change the headers.

I must say that I’m honestly so disappointed in how much of a pain it has been to maintain this API. Originally, twitch integration of a list of current live streams of the game was something we implemented in only a few hours. Then the API keys were added and it became significantly more difficult to do anything, and now this. I just want a quick solution to display the information that’s already publicly available at Twitch. At this point, I’m honestly tempted to just scrape it directly rather than bothering with the API at all.

[Elyot_Grant]

Just to give an idea of the effect this is having on our community, here’s a screenshot from our Discord server:

[Elyot_Grant]

Solution found! Somebody in the Discord server pointed out that ?api_version=5 can be added to the URL.

We read the whole documentation and never found this. It would have been nice to know.

But at least we have a solution for now.

[BarryCarlyon]

@Elyot_Grant

If I have to add the version in there somewhere, it’s fine. But I can’t change the headers.

Why can’t you change the headers? It’s a fairly standard thing for a application making a HTTP request to be able to set headers.

@Elyot_Grant

And I’m actually very upset that it wasn’t communicated to us in any fashion at all

There have been numerous emails.
Numerous updates to the developer documentation and updates pushed out via the Developer Weeky Twitch stream and this very forum

Twitch API v3 and v5 Deprecation Updates

Update (2019/07/25): Please see our latest information regarding the shutdown timeline for v3 here. Greetings from Twitch, We have important updates to share regarding deprecation of v3 and v5 of the Twitch API. As previously communicated in February 2017 and documented in the v5 API guide, Twitch planned to remove third-party support for the v3 API on December 31, 2018. However, we are delaying this process by a few weeks to provide developers more time to prepare for the upcoming changes. S…

Twitch API update – delaying v5 end-of-life

Last fall, we introduced an all-new API designed to simplify core data models and create a consistent, reliable experience for the Twitch developer community. Alongside this update, we also immediately deprecated and planned to remove v5 by the end of 2018. Based on your feedback, we are delaying the end-of-life for v5 of the Twitch API. While we recommend using the new Twitch API on new projects, we recognize it does not yet solve for every use case we want to promote. We’re still working to …

Twitch API v3 Shutdown Timeline

On November 15, 2016, Twitch announced that the v3 API had been deprecated with the release of v5. Today, we’re moving forward with a controlled shutdown of v3 and would like to share our plans. Starting on August 12, 2019, we will begin implementing scheduled outage windows of v3 endpoints over several weeks ending with a complete shutdown of v3 endpoints on September 12, 2019. If you do not take action to migrate your application to v5 of the API, your application will experience outages duri…

The last post of which covers the “shutdown” testing timeline

@Elyot_Grant

In any case, we rely on client side API calls through Adobe AIR, which does not support non-default headers for GET requests because we’re not running the requests from an application security sandbox. We can’t add the Accept header, it literally gives a runtime error.

You should move off Air, to something that does let you set custom headers making requests, last time I was in flash (years and years ago) you could make requests with custom headers. (I actually thought air was dead but turns out it had a release recently)

@Elyot_Grant

We read through all of the API migration guides when you first sent us the email, and we were assured that everything would be fine:

https://dev.twitch.tv/docs/v5/guides/migration/#default-api-version

This section clearly states the requirement to be able to set the Accept header.

Note that default version of the API will not be updated to v5 after the v3 shutdown and therefore the Accept header will be required for any request to the kraken namespace.

This section above, you decided to omit from your initial screenshot of the docs, or you seem to have a very outdated screenshot.

Whilst the undocumented solution of api_version=5 currently works this does not guarantee it will continue to work.

Generally speaking, most APIs expect the ability for you to set custom headers.

Probably the easiest solution for you is for your Air Application to make a request to your backend server, and then your server can fetch and maintain a cache of who is live on the stream and deal with all the fun of the actual request headers and all. You probably already have such a server in order to serve updates for your app.

[Elyot_Grant]

The problem wasn’t the lack of emails notifying us about the changes and shutdown timeline. You sent us the notification on July 25th that our app was still calling v3 endpoints, and then a reminder in the July 31st dev newsletter about the shutdown timeline.

The problem was that after you sent us those emails, and we had investigated and made our migration plans by July 26th, you CHANGED YOUR MIND on backward compatibility of the headerless behaviour without notifying us. Posting on your twitter feed or your developer forum didn’t reach us. I’m running a small game development and publishing company and I don’t have time to monitor all these channels to catch a small-but-crucial change to the previously-announced migration plan.

The screenshot I showed was from July 25th, the day you sent us the fucking email telling us that we needed to migrate. We read all the docs that day.

You should move off Air

Prismata is a product with 900k owners and we’ve been using this API for years. We have a very active community of players, we can’t just port tens of thousands of lines of code because twitch decided to change their API.

Flash is pretty dead but there are still many developers making desktop and mobile apps in AIR. You can use custom headers if they’re non-standard ones but you can’t use any of a number of restricted terms when running unsandboxed, and Accept is one of those terms. There is a list here: URLRequestHeader - Adobe ActionScript® 3 (AS3 ) API Reference

It likely requires little-to-no effort on your end to continue to support the headerless calls, so I hope you will do so.

[BarryCarlyon]

@Elyot_Grant

It likely requires little-to-no effort on your end to continue to support the headerless calls, so I hope you will do so.

I’m not Twitch staff. Just a moderator on these forums.

@Elyot_Grant

The screenshot I showed was from July 25th, the day you sent us the fucking email telling us that we needed to migrate. We read all the docs that day.

There is zero reason to be rude about this matter.

Twitch can and will change the docs as it needs to as updates and changes come from the relevant teams inside Twitch. As clearly it has done in this case.

@BarryCarlyon

Probably the easiest solution for you is for your Air Application to make a request to your backend server, and then your server can fetch and maintain a cache of who is live on the stream and deal with all the fun of the actual request headers and all. You probably already have such a server in order to serve updates for your app.

This is the simplest solution, just swap the call from Twitch directly to your backend server. Then you can benefit with your server caching the streams from Twitch or even utilizing webhooks.

Additionally you will need to change when v5 is removed completely and you have to move to Helix. As v5 is also deprecated

[riking]

@BarryCarlyon

There is zero reason to be rude about this matter.

False.

@BarryCarlyon

This is the simplest solution, just swap the call from Twitch directly to your backend server.

That’s a huge monetary cost, servers aren’t free.

[Elyot_Grant]

@BarryCarlyon

I’m not Twitch staff. Just a moderator on these forums.

Then you shouldn’t be suggesting to the CEO of a game development studio that they change their entire technology stack.

Nor should you be making up excuses to defend a deprecation policy and communication strategy that is clearly ineffective.

Is somebody from Twitch going to respond or am I going to have to send an angry email to JT?

[BarryCarlyon]

@riking

There is zero reason to be rude about this matter.

False.

Alright then there is no need to start swearing. Please keep it polite and sensible on the forums.

@riking

This is the simplest solution, just swap the call from Twitch directly to your backend server.

That’s a huge monetary cost, servers aren’t free.

They already have a(t least one) server, in order to deliver updates to their application. Adobe Air is a desktop application.

@Elyot_Grant

Then you shouldn’t be suggesting to the CEO of a game development studio that they change their entire technology stack.

It is a simple fix from the desktop side, swap the URL to your backend/updates server and the update server can proxy the request. I was just trying to make a useful suggestion to future proof you if you don’t intend to move off Air.

You will need to make further changes when v5 is removed. So consider getting ahead of the game and moving to Helix now and/or utilizing webhooks, if that’s useful to reduce the overhead from long polling.

API’s change all the time, and you need to adapt when old versions of the API are removed. This is not just limited to Twitch API’s.

@Elyot_Grant

Is somebody from Twitch going to respond or am I going to have to send an angry email to JT?

I’m sure Twitch would appreciate any feedback on the matter.

@BarryCarlyon

I’m not Twitch staff. Just a moderator on these forums.

@Elyot_Grant

Then you shouldn’t be suggesting to the CEO of a game development studio that they change their entire technology stack.

I forgot to add that I’m also a developer. So my suggestion also comes from experience and knowledge, and what I would do in this situation.

[Elyot_Grant]

@BarryCarlyon

They already have a(t least one) server, in order to deliver updates to their application. Adobe Air is a desktop application.

This comment betrays your ignorance about the whole situation. Like almost every other game developer out there, Steam does the updating for us. And even for our non-Steam applications, we rely on filestores (Amazon S3, etc.) for updates, which can’t proxy HTTP get requests.

Of course I can fire up an EC2 node or whatever just to gather and stream the twitch data, but that’s a stupid amount of overkill for what we want to do (just displaying publicly available information from Twitch).

@BarryCarlyon

So my suggestion also comes from experience and knowledge, and what I would do in this situation.

The suggestion that offended me deeply was when you said to “move off Air”. If your first suggestion to the lead engineer behind a successful application is that they change their entire client-side technology stack (including the game engine itself), of an app that’s been running just fine for years, then it’s hard for me to think much of your “experience and knowledge”.

People use all kinds of different technology to make games. Twitch should be aiming to create APIs that make access to them as easy as possible for as many game creators as possible. Instead, they’re needlessly imposing burdens that make it more difficult for some developers. I assume this is something they would want to hear about (and rectify).

[Breci]

This is really going out of topic…
Like seriously calm your ego Elyot… I don’t care if you are CEO or in the game industry, you are just being agressive in your posts. And posting a screenshot of people sayign they will stream to mixer isn’t something that will help the dialog

If your stack can’t change the headers there is some things to address in it because it means you have some kind of technical debt. There will be many similar problem in the future with all the different API that can be used in game dev so you need to take time to sort that.

If you are calling Twitch API directly from your game, you should consider moving that on your servers, so you can reduce the amount of API that your game is dependant from and it will give you way more control on this and you could even build feature, like featured streamers, showcase people using new content or stuff like this.

[jbulava]

@Elyot_Grant The API team is aware of your challenge in regards to setting headers for making v5 calls and we all appreciate your feedback in the process. I’m glad to hear that you found a solution using api_version=5 directly in the request. Though possible, it was never added to the documentation as it was not the method in which we wanted developers to declare a version. Since this will most likely not change before the sunset of v5, I think this is your best course of action. I will follow up if the API team has a different recommendation.

You are correct that the handling of the default API version changed since the first email communication about the migration guide and we did not communicate further when the guide was updated. We did not anticipate any issues. We’re sorry to hear this had been an inconvenience, though this is exactly why we are running scheduled shutdown windows. We want to make sure we catch any issues alongside developers ahead of the final shutdown to minimize long or undetermined amounts of customer downtime.

Please let us know if you have further questions.

[Elyot_Grant]

Thanks for a proper response, Jon.

If I might add a suggestion, the easiest implementation for us was back when we didn’t even need the API keys at all and could just query a URL to grab the json object for the data at https://www.twitch.tv/directory/game/Prismata. That let us add a little in-game widget for the currently-live streams in just a few minutes, which was by far the most useful thing for us. Now it’s much more difficult to get started and you can’t even make API calls without an account, so you might want to consider a solution like this in the future if your goal is to make the APIs more accessible and easy to use for newer devs.