Summary

Conducttr uses OAuth 1.0 for authentication
The same URL is used to GET and POST data to attributes.
GET requests return the defined parameters as a simple JSON object
API 1.0 requires Access Token and Consumer Key
API 1.1 & 1.2 require Consumer Key

Unauthenticated GET requests are permitted with Consumer Key.
POST requests are only permitted with authenticated requests.

About API Methods:
  • You define your own
  • You can exchange attribute data using a Method without creating an API Trigger.
  • You do not need to create a Method if you only wish to trigger Conducttr and not exchange Attribute data.

External applications contacting Conducttr

Conducttr's API (Application Program Interface) is used to connected external applications to your project to:
  • send and retrieve Attribute values
  • trigger Conducttr
  • trigger external applications.

The same URL is used to GET and POST data to Attributes.
GET requests return the defined parameters as a simple JSON object

How to program the client application to work with the API is beyond the scope of this document but here's what you need to know regarding three key aspects:

  • Authentication- creating a secure connection to Conducttr
  • Methods- the way to exchange Attribute data
  • Triggers- the way to trigger Conducttr.

Authentication

Requiring an external application to "authenticate" itself to your project allows the app and Conducttr to operate securely.

Conducttr uses OAuth 1.0 for authentication. You can also receive and send Unauthenticated requests.

When you create an API for your project the authentication details can be found on the Authentication page (see below). In your Conducttr project, navigate to the "API" widow and it'll be there.

When the external app tries to talk to Conducttr it will send the Access Token and the Consumer Key (to identify the app). Conducttr and the app use the matching secret keys to know they're allowed to talk to each other.

NOTE: API 1.1 and 1.2 need only use Consumer Key



Methods

A "method" is a common term that means a procedure or function for getting something done.
You can exchange Attribute data using a Method without creating an API Trigger.

Conversely, you do not need to create a Method if you only wish to trigger Conducttr and not exchange Attribute data.

To create a Method, navigate to the "API Method" page, click +You give your Method any name you wish.


Exchanging Attribute Data

To exchange data with the external app, click the "Add Another" button to add a parameter to your Method.

Give the parameter a name - this is what will be sent to the API - and then map the parameter to an Attribute.

In Figure 121 an API parameter has been created called "player_health" which is mapped to Audience.health.
Now, when the API issues a POST instruction, the value of the player_health parameter (e.g. " player_health=6") will be passed to an Audience member's health Attribute.


The same Method is used for POST (update the Attribute value) and GET (retrieve the Attribute value).

A GET instruction will return all parameters in the method. For method below a GET returns:{"results":[{"light_is_on":"1"},{"character_sleeping":"1"}],"response":{"status":200,"message":"OK"}}


With API 1.0, a POST instruction must include ALL parameters in the method or else parameters not included will set the Attributes to NULL