Twitch API client on scala

Pure Functional Twitch API client on scala

Authentication

Twitch API supports two different authentication mechanisms:

• Public application Client ID is used to integrate with the API. This schema provides lowest rate limits.
• Public Client ID and Client Secret are used to generate Application access token. This token is included in all requests
  as HTTP header. This schema provides higher rate limit. Token has finite lifecycle and must be recreated after expiration.

For more information refer to: Twitch apps and authentication guide.

Usage

First of all you need to define which authentication schema you are going to use. You may authenticate based on Client ID

val clientId: String = "your-client-id"
val env = io.twitchapi4s.ClientIdTwitchEnv(clientId)

or Token

val token: String = "your-twitch-token"
val env = io.twitchapi4s.TokenTwitchEnv(token)

Once environment is created you should create endpoint with necessary operations, for example,

import scalaz.zio.interop.catz._
import scalaz.zio.interop.catz.mtl._
import io.twitchapi4s.zio.client._
import io.twitchapi4s.zio.client.TwitchEndpoint._
val endpoint = new TwitchEndpoint[TwitchEnv](backend)
  with GamesEndpoint[TwitchEnv]
  with StreamsEndpoint[TwitchEnv]
  with UsersEndpoint[TwitchEnv]
  with VideosEndpoint[TwitchEnv]

This snapshot and next examples are based on implementation for ZIO but examples for Monix are completely the same except package name.

Now we are ready to execute some queries:

runtime.unsafeRunSync((for {
  topGames <- endpoint.getTopGamesR()
  topGame = topGames.data.head
  videosByGame <- endpoint.getVideosR(GameVideoId(topGame.id))
  video = videosByGame.data.head
  userById <- endpoint.getUsersR(ids = List(video.userId), logins = Nil)
  followers <- endpoint.getFollowsR(fromId = Some(video.userId), toId = None)
} yield (userById, followers)).provide(env))

This approach works fine but have couple drawbacks:

• If you use authentication based on Client ID (ClientIdTwitchEnv) then your rate limit is low and you may get
  io.twitchapi4s.RateLimitExceded Exception.
• If you use authentication based on Token (TokenTwitchEnv) then your token may expire at any time and you have to
  generate new one.

To overcome both these issues you may create endpoint with another environment
io.twitchapi4s.zio.client.RecoverableTwitchState

import scalaz.zio.interop.catz._
import scalaz.zio.interop.catz.mtl._
import io.twitchapi4s.zio.client._
import io.twitchapi4s.zio.client.TwitchEndpoint._
val recoverableEndpoint = new TwitchEndpoint[RecoverableTwitchState](backend)
  with GamesEndpoint[RecoverableTwitchState]

Now to load some data from Twitch you should write something like that

val env = WithoutTokenEnv(clientId, clientSecret)
val ref = runtime.unsafeRunSync(Ref.make[RecoverableTwitchEnv](env)).toEither.right.get
runtime.unsafeRunSync((for {
  starcraft <- recoverableEndpoint.getGamesS(Nil, List("Starcraft"))
  starcraft2 <- recoverableEndpoint.getGamesS(Nil, List("Starcraft 2"))
} yield (starcraft, starcraft2)).provide(RecoverableTwitchState(ref))

This code

• creates mutable scalaz.zio.Ref with WithoutTokenEnv which contains Client ID and Client Secret
• wraps this Ref into RecoverableTwitchState
• provides this state in Effect

Client ID and Client Secret will be used to generate token before first request to Twitch. If authentication exception is
thrown at some moment then recoverableEndpoint will try to recreate token again before propagation this exception to outer
code.

You may find more examples for ZIO and Monix in classes io.twitchapi4s.zio.client.TwitchTest and io.twitchapi4s.monix.client.TwitchTest.