Moving to v5 of the Twitch API

Posted by adrian on November 18th, 2016

I got an email as part of the Twitch Developer community about upcoming changes to the Twitch API (Kraken). On an initial read I was a little bit confused and slightly worried as the changes come into effect quite quickly. So I thought it was worth a look to see how problematic the changes were going to be and update a couple of my streaming widgets to use the new API version. now that I’ve worked through the changes I’m not so worried but do read on if you want to know what I make of the required changes.

The key change is that you can no longer refer to channels or users using the text name, you have to resolve this to an id first and then make your call to the API.

Here’s a call you may have made to the v3 API using javascript and ajax:

 
$.ajax({ 
  url: "https://api.twitch.tv/kraken/channels/unshapedadrian", 
  dataType: 'json', 
  headers: { 
    'Client-ID': 'myClientId' 
  }, 
  success: getChannelIdCallback 
}) 

This call will return the channel data for my channel as a json object, note that I use the name of my channel in the call. In the v5 API you must use the _id and not the actual name of the channel so if we tried to make this call it would fail with an http error 400

$.ajax({ 
  url: "https://api.twitch.tv/kraken/channels/unshapedadrian", 
  dataType: 'json', 
  headers: { 
    'Client-ID': 'myClientId',
    'Accept': 'application/vnd.twitchtv.v5+json'
  }, 
  success: getChannelIdCallback 
})

Note that I’ve forced the call to go to the new v5 API by adding the relevant Accept header

So the question is how do we get the id to replace the name in the call to the API. The initial document from Twitch suggested using a v3 API call to /users but this seems really daft to me as the v3 API will be deprecated in Feb 2017 and removed in Feb 2018 so I had a browse around to find another way to resolve the name. Twitch have several search APIs that you can use, one of which handily is a user search and the relevant json returns contains the id so we can use that to resolve the name to the id. I came up with this little piece of code, a call to the Twitch API and a callback to handle the data to convert a channel name to an id you can see this implemented in my boxart application here twitchboxart.


var channel = 'unshapedadrian'

//Need this section for Kraken v5 API calls to convert names to ids

//v5 needs a Channel Id rather than a channel name

function getChannelId() {

  //Using ajax here, could have used getJSON but the error handling is awful
  $.ajax({
    url: "https://api.twitch.tv/kraken/search/channels?query=" + channel,
    dataType: 'json',
    headers: {
      'Client-ID': 'myClientId',
      'Accept': 'application/vnd.twitchtv.v5+json'
    },
    success: getChannelIdCallback
  })
}

function getChannelIdCallback(data) {

  //We need to set the channel Id rather than the name
  channel = data["channels"][0]["_id"];
  //Now we can get the current game
  getCurrentGame();
}

There are a couple of other changes of note one of which you can see in the above call to search, in v3 you could call /search/channels?q= but in v5 you must use query rather than q like so /search/channels?query=. The other change I noticed was that the _links section which was normally returned in the json data is now no longer returned, this is not a big issue as it was just used to describe options on the API you called which are in the documentation anyway. I need to firm this code up slightly as the search could return multiple results and you’d want to check through them and match the correct one however a high percentage of time the correct response is in the first member of the array.

I streamed the fixes to my code, you can find the troubleshoting, debugging and code updates in the Video on Youtube here or check out my Twitch channel

 

 

 

/* */