TWiT API

From The Official TWiT Wiki
Jump to: navigation, search


In 2015, TWiT redesigned the twit.tv website. As part of this redesign, an API was introduced which would allow third parties to access TWiT's data. This data includes shows, episodes, hosts and guests, posts, live streams, and more. The TWiT site itself uses the API as well (although it has access to a few extra features that are not available to third parties, such as updating episode data via the API).

About the API

The new TWiT site is a departure from previous TWiT web sites, and from almost any other site you've ever visited. Instead of building a traditional web site, we created a headless Drupal backend with a ReSTful API. The TWiT site is a consumer of the API. Other consumers of the API include third-party, fan-made apps and maybe you too!

We encourage everyone to play with our API and build new things. You can use any programming language and operating system you like, as long as you can make ReST calls and parse the JSON results. For more information on ReST start with this article from Dr. Dobbs.

The API documentation is available at Apiary. Before you begin using the TWiT API for real you'll need our approval. Begin by signing up for a free account at our 3scale page: https://twit-tv.3scale.net/ - they're the key masters. As soon as we see that you've requested API access and have a validated account, we'll grant access. However, approval is a manual process that may take a day or two, so please be patient. (Please do not use a temporary, disposable email address or you will not be approved.)

TWiT reserves the right to revoke keys if you start pulling too much data or misuse the data. We're working on an acceptable use policy, but in general have at it. We'll start you with five GET requests a minute. If you need more, or want to ask about the API, email api@twit.tv but remember that it's a work in progress and we're just learning how to use it, too.

API Tutorials

There are some episodes of Coding 101 that demonstrated how to use the API. Look for episodes 74, 80, 81, 82, and 83.

Accessing the API

In order to access the TWiT API, you must sign up for the TWiT API at 3scale. Your account will likely be approved within a few business days. The only accounts not approved are those who have not verified their e-mail address with 3scale, people who have repeatedly posted their private app keys in public, known trolls, or people using known throw-away e-mail domains. We also reserve the right to revoke access to those found abusing the API.

API Authentication is provided by 3scale. 3scale is an API provider service where you can register your API app and apply for access to the TWiT API via an application plan. An application plan has rate limits. These rate limits are the number of API calls that your application can make in a certain time limit.When you are granted access to the TWiT.tv API you can begin making requests against the API. TWiT.tv's API uses an application identifier and key pair pattern. While the API id may or may not be secret depending on your implementation, the app key is secret and should be protected.

App keys that are found to be posted in public online will be have their access revoked.

Increasing GET Requests

The TWiT API limits GET requests to 5 per minute. We realize that's not much, but we limit this to keep requests limited to unknown developers. If you release an app and require more, we can increase that limit for you when you launch your app. (We typically do not increase the limit for apps in development.) We will not give your app unlimited requests! We strongly suggest keeping a local (or cached) copy of data for your own app or site rather than constantly hitting the API for every request from every user. (The API responses are a bit wordy and can be slow, so your code will perform much better if you're hitting your own local copy instead of constantly making API requests.) We even do this on the twit.tv site and our internal tools...because hitting the API every time is not good for your app's performance.

If you exceed your usage limit, the API will return a 500 error.

External Links