How to use the Mission Center Web services

First, why use web services?

The Mission Center Web services is a way to have an external system exchange data with the Mission Center. This could be useful for a variety of reasons:

• You need to synchronise a population of learners that is already available in another database, another platform, another system
• Your learners are already using another app (or webapp), and you want them to easily reach the Teach on Mars platform with a single click
• You need to gather the learning analytics from the Teach on Mars platform in order to merge the data to that of another system
• You own another platform and you need Teach on Mars users to open this platform directly from the app and be authenticated
• You need to manage training course registrations in the Teach on Mars platform automatically according to some data in a third party system.

These are the main scenarios in which the Mission Center Web services can be useful.

Let's see how it works.

Request and response structure

The API is HTTP and JSON based. Data passed in POST and PUT requests is stored in the body as JSON. In responses, the data is also stored in the body response and structured as JSON. 

To be able to send requests to these webservices, you need an API key and an API secret, but you also need to construct your request in a certain way so that it is accepted by the server. API credentials and context information are stored in the HTTP headers. The authorization protocol is designed to include elements that change from one request to another, so the headers will have to be constructed dynamically. We will see how in the next section.

Teach on Mars API Headers reference

In order to call any ToM service, some HTTP headers must be sent to authorize the request. Here's a list of the headers required in any request send to the Mission Center.

API hash construction

SECRET = The API secret linked to this API key
RTS = X-TOM-RTS Header
APP = X-TOM-APP Header
REQUEST_HASH = MD5 ( BODY REQUEST_URL)
NONCE = X-TOM-NONCE Header

STR_TO_ENCRYPT = CONCAT( SECRET RTS APP REQUEST_HASH NONCE )

HASH = SHA256 ( STR_TO_ENCRYPT )

Code example

Using PHP

$requestTimestamp = time();
$nonce = time().generateRandomString(20);
$hash = $API_SECRET.$requestTimestamp .$APP.md5($data.$wsUrl).$nonce;
$hash = hash('sha256', $hash);

$ch = curl_init($wsUrl);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
 'Content-Type: application/json',
 "X-TOM-APP: $APP",
 "X-TOM-API-HASH: $hash",
 "X-TOM-API-KEY: $API_KEY",
 "X-TOM-RTS: $requestTimestamp",
 "X-TOM-NONCE: $nonce",
));
$result = json_decode(curl_exec($ch));

Discover the Teach on Mars web services

To discover how your system can interact with Teach on Mars' Mission Center, read the documentation for Teach on Mars Web Services.

Try out the API with Postman

You can also try the Teach on Mars API using Postman.