Migrating from the old api

Is this page for me?

If you love video games, and you like building sites then it is very likely the answer is yes! This is even more true if you had invested the time to use the Justin.tv API. The aim of this page is to describe why we've built out a new API and what analogues exist between the two of them.

Why?

Because it is a good idea! The old API was built to satisfy a different set of requirements than those that we have now on Twitch. On top of that some bad decisions were made, so instead of trying to work out a migration plan we thought it better to build it from the ground up with all of the learning we gained from the last pass. The list of key improvements:

Super RESTful
Self describing - as detailed by our buddy @Immad over at Heyzap
Versioned - i.e. we can now provide backwards compatibility
OAuth2 - so much easier to get right than OAuth1!
Secured by scopes - fine grained access to certain properties
Consistent

The last point, consistency, requires more details. Historically we had absolutely no rhyme or reason as to what we returned to users, our thought process was to return exactly what you needed, however that was not scalable and made client side code so much more complex than it needed to be. Now if we say you'll get a User object back, you'll get a User object back regardless of which part of the API you're using.

Finally, this API has a full integration suite, so should we change our objects - we know.

How do I get support?

Right now as we ramp up the support infrastructure of this new API your best bet is going to be making sure you read this wiki, for questions you can use the Twitch API mailing list.

Migration guide

If you're working on a front end, you probably just want to use our JavaScript library - it gives you super easy access to all of the features as well as letting you make use of Twitch Connect, which lets you link your user accounts to twitch user accounts and grants you the ability to use the API as those users.

Srsly, you probably just want to use the JS library :)

... However if you use a backend to make queries for you, or if have a browser extension, etc, you probably want to know which old calls map to which new calls. This list will evolve, and if you want something added to it let us know on the Twitch API mailing list or open up an issue on this repo.

Some things are missing!

Yes, this is true. Some things will not have a like for like implementation, some things will be dropped, some others will be worked on. The old API broadly broke down into some key categories;

the REST API
the chat embed
the SWF API

So far we have concentrated primarily on the REST API. We are also building a brand spanking new chat API to replace the embed - we want you to be able to use chat as a first class citizen, not through some proxy that we control. We're also planning to build a brand new SWF integration, if you want to use our SWF player you should use our existing one, however it is tied into the old API so I warn you now... your mileage will definitely vary and we'll not be well suited to helping you a whole bunch.

Below we detail all of the things that will stay gone, if you've any issues with this list then you are encouraged to let us know why it is a bad idea.

things that will stay missing from the REST API

stream callbacks
listing user events
channel events
chat send message (will be replaced by the new chat API)
category listing (Twitch only has one category - GAMES!)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrating from the old api

Is this page for me?

Why?

How do I get support?

Migration guide

listing streams

summary

search

user data

channel data

archive data

Some things are missing!

things that will stay missing from the REST API

Clone this wiki locally