Twitch Kraken version update

[celluj34]

I received this email, as I'm sure you all did too:

https://blog.twitch.tv/action-required-twitch-api-version-update-f3a21e6c3410

ACTION REQUIRED: Twitch API Version Update

TL;DR: Read all of this. It’s important and will break your integrations. We’re changing how the Twitch API works and old versions of our API will be deprecated and removed.

Today, we’re delivering a change that you’ve requested for quite some time! Twitch API v5 is available now and uses IDs to reference users instead of usernames. This new API version puts us in a better position to add new functionality and features to both the API and the Twitch website.

You can start using v5 and upgrading your integrations today. You simply pass the application/vnd.twitchtv.v5+json header on your requests. We’re working hard to deliver reference documentation on the affected endpoints by mid-December. Here is a quick example:

Retrieving a user in v3
curl -H 'Client-ID: XXXXX' \
-H 'Accept: application/vnd.twitchtv.v3+json' \
https://api.twitch.tv/kraken/users/dallas

Retrieving a user in v5
curl -H 'Client-ID: XXXXX' \
-H 'Accept: application/vnd.twitchtv.v5+json' \
https://api.twitch.tv/kraken/users/44322889

There are other changes to note with this version:

• The _links object is removed from all responses. As a developer, you will be responsible for handling the paging offsets when polling the API.
• Added sub-second precision to time fields.
• Removed /games/featured endpoint.
• Removed delay, background, and banner from the channels response object.
• Replaced q and type parameters on the search endpoint. The q parameter is now called query. The type parameter is always set to suggest.
• Removed paywalled field from the video response object.
• Removed /kraken/chat, /kraken/chat/emoticons, and /kraken/chat/emoticon_index.

What does this mean for me as a developer?
You need to migrate your code to use v5. On February 14, 2017, we will be removing v1 and v2 of the API and transition v3 into a deprecated state. In one year (February 14, 2018), v3 will be removed from the API. We hope that this gives enough transition time for your integrations.

If your integration relies on username now, you can use the /users endpoint to translate from a username to an ID as shown below.

curl -H 'Client-ID: XXXXX' \
-H 'Accept: application/vnd.twitchtv.v3+json' \
https://api.twitch.tv/kraken/users/dallas

For questions regarding this transition, please ask on the developer forum thread. We know this is a big transition and want to help in any way that we can.

Thank you for being a part of the Twitch Developer community!

[celluj34]

Just wanted everyone to be aware of what was happening. I don't know if it affects this project at all, but I thought it couldn't hurt.

[AlcaDesign]

My bot has been name-oriented since I started it so I hope they make a proper way to convert name to ID in v5.

[celluj34]

I think a lot of people were, because that's how it was done. If you're storing them somehow, I think you'd just have to crawl the API, converting usernames to IDs as you go. It's a crap way to do it, but better now than later, imo.

[AlcaDesign]

Luckily I've been doing this without a DB, but I will still have to rewrite around 1,000+ lines of code to adapt.

[jordanmkasla2009]

The FAQs Twitch answered in the discussion thread on v5 indicates one method of getting the user Id for users:

How do I get a user ID from a login name in v5?
We heard you loud and clear. The new API lives here:

https://api.twitch.tv/kraken/users?login=dallas&api_version=5
We're iterating on this API. Please be patient for updates.

You can also get the User Id (subject to change) whenever the message event fires in tmi.js through the userstate object.

{
    'badges': { 'broadcaster': '1', 'warcraft': 'horde' },
    'color': '#FFFFFF',
    'display-name': 'Schmoopiie',
    'emotes': { '25': [ '0-4' ] },
    'mod': true,
    'room-id': '58355428',
    'subscriber': false,
    'turbo': true,
    'user-id': '58355428',
    'user-type': 'mod',
    'emotes-raw': '25:0-4',
    'badges-raw': 'broadcaster/1,warcraft/horde',
    'username': 'schmoopiie',
    'message-type': 'action'
}

[Felwin]

If now we should handle users by ID (I guess the final idea is too allow people to change their username), shouldn't be the same for channels ?
Look like yes, the API v5 offers Get Channel by ID
BUT as for now with tmi.js everything channel related is with the name, to join or when receiving a message.
I think this is a real issue, maybe not to join, we can make Get Channel by ID to get the name of the channel to join, but every-time a message arrived, we don't have the channel ID, only the name.
So what's the plan ? every-time we join a channel we should keep the memory of channel name/ID correspondence ? (because obviously now we want to keep in our databases only the IDs)
Will they give the channel ID when an event message occurred ? Is that already the case, just tmi.js didn't update yet ?

[AlcaDesign]

When you receive a message, you get a userstate object. The key "room-id" is the channel ID.

[Felwin]

Thanks, that's the answer I needed ( should have figure it out by myself though...)
Considering the news, wouldn't it be nice to be able to join with the channel ID directly ? and when the promise fire to get the channel ID in the data returned ? (now it's only the channel name with #)

[AlcaDesign]

I guess everything would need to accept an ID in that case, but they're using strings for the IDs. If you were to pass a string ID, it'd be indistinguishable from a channel name. Perhaps you should form a Channel class that will store the name and the ID and then it's clear.

class Channel {
    constructor(data = {}) {
        this.id = data.id || null;
        this.name = data.name || null;
    }
}

module.exports.Channel = Channel;

client.prototype.join = function(channel) {
        let chan = channel;
        if(channel instanceof Channel) {
            chan = channel.name;
        }
        /* ... */
    };

const tmi = require('tmi.js');

let client = new tmi.client({ /* ... */ });

const channels = {
        alca: new tmi.Channel({
                id: '7676884',
                name: 'alca'
            })
    }

client.join(channels.alca);

I don't hate this, but at least it's clear-ish. Or just an object. Doesn't have to be a whole class thing. The class is just a disguise for a pretty plain object.