bt.tn REST API

This is a quick hands-on introduction to bt.tn REST API usage. Check the bt.tn REST API reference for details.

Trying it Out

To get started with the bt.tn REST API, you will need the cURL command line HTTP client. This is usually pre-installed on Mac & Linux but needs to be installed separately on Windows. Test that it’s set up by running curl from the command line.

To try out the REST API:

  • Log into my.bt.tn.
  • Pick a bttn you want to use and click the small "Properties" icon next to it.
  • Click on "Edit" under "Advanced Properties" and toggle "Publish counter" and "Publish feed" from "No" to "Yes".
  • Copy the feed URL and press "Save".
  • You can test that the feed URL is accessible by opening it directly in the browser.
  • Alternatively, use cURL from the command line with curl https://api.bt.tn/2014-06/ID/feed&npsb; where ID is your bttn ID.
  • Press the bttn or launch a virtual bttn by selecting the "Launch virtual bttn" rocket icon next to the bttn name in your list of bttns and press that.
  • Repeat previous cURL command to see the new bttn press event in the feed.

You can see the full list of API endpoints available by browsing the bt.tn API Reference documentation.

Retrieving Your API Key

Some endpoints require you to be authenticated using an API key. You can find them under the "Authenticated" header in the API Reference. To retrieve an API key you can use for development:

  • Log into my.bt.tn.
  • Click your name in the upper right and select "Account Settings".
  • Scroll to the bottom to "Generate an Api-Key for REST API access" and click the "Generate" button.
  • Pick a unique name for your application and click "Generate".
  • Your API key will be displayed - copy it to your clipboard.
  • From the command line, run curl --header "X-Api-Key: API_KEY" https://api.bt.tn/2014-06/bttns  where API_KEY is the key you just copied, to see the list of bttns the application has access to.

By using the API key retrieved via my.bt.tn, you will be able to see only your own data. If you want to access data on behalf of other users, you will need to create a bt.tn application and use OAuth to request access to users’ data. At the moment, this functionality is provided only to our partners. If you would like to become a partner, please email info@bt.tn.

Browser Example

Below, you can find the source of a simple single page app using the bt.tn REST API to display the counter values of two bttns: 

<!DOCTYPE>
<html>
<head>
  <title>bt.tn Duel</title>
  <script src="https://code.jquery.com/jquery-1.11.0.js"></script>
  <script>
    var BASE = "https://api.bt.tn/2014-06/", BTTNS = [1, 3];
    $(function() {
      (function update() {
        $.get(BASE + "counter?id=" + encodeURIComponent(BTTNS.join()), function(data) {
	  $("body").html("");
	  $("body").append(data[0].counter);
	  for (var i = 1; i < data.length; i++)
	    $("body").append(" : " + data[i].counter);
          setTimeout(update, 2000);
        });
      })();
    })
  </script>
  <style>
    html, body { height: 100%; }
    html { display: table; margin: auto;  }
    body {
      display: table-cell;
      vertical-align: middle;
      font: bold 20vw monospace;
    }
  </style>
</head>
<body>
</body>
</html>

To see it in action, copy paste the code above into a file with the extension ".html" on your computer and open it with your browser.

Here's a quick overview of the code:

  • the first script tag includes jQuery
  • the second script tag contains the app spefic code:
    • first we set some constants, such as the API BASE and IDs of BTTNS - you can update one of these to be the ID of your bttn, which we configured in the "Getting Started" section.
    • once the DOM has loaded, we create and immediately call the update function
    • the update function makes one HTTP GET request to fetch the counter value of both bttns - this is possible from any domain thanks to CORS support in the bt.tn REST API
    • once the request completes, we update the body HTML to display the counter values of the two bttns
    • finally, we use setTimeout to have the update function run again after 2 seconds
  • the style tag is used to set the font and position of the body text

Server Checklist

To create and release a standalone web app using the bt.tn REST API, you will need to complete the following steps:

  • Make sure you have a bt.tn app ID. These are currently only available to partners. To become one, email info@bt.tn with some info on how you'd like to integrate with bt.tn.
  • Create an API endpoint on your server for accepting web hook requests from bt.tn servers.
  • Add support for the bt.tn OAuth flow to your web app:
    • Add a link to your UI that your users can click to give your app access to their bt.tn accounts.
    • Clicking the button will redirect the users to bt.tn. Your app ID should be part of the URL to redirect users to. Here, they may log in, if they aren't logged in already. Once logged in, bt.tn will display a confirmation page, then redirect the user back with a code as a request parameter.
    • Use this code together with your client ID (app ID) and client secret to retrieve an access token via the grant access token endpoint. You should most likely store this access token in your database for future use.
  • You can now use the access token via the "Authorization" HTTP header to access REST API endpoints that require authentication:
    • First, list the user's bttns and display that list via your own interface, so the user can choose which bttn to link to your app. You should most likely store the bttn ID in your database for future use.
    • Then, register your web hook URL for this bttn. You may want to pass some random key that you store in the database alongside the user as part of the web hook URL to prevent spoofing.

That's it! Now whenever the user presses their bttn, you will receive a web hook HTTP request. Verify it using the random key, if available, and process as required by your application.

Note that users may disassociate their bttns from your application via my.bt.tn or by authorizing another app, so you may want to periodically check if your access token is still valid and your web hook URL hasn't been changed using the get web hook endpoint.