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.
|X-TOM-API-KEY||The API key that you've been given|
|X-TOM-APP||A reference code that represents the application|
|X-TOM-RTS||The Unix timestamp of the request (seconds since Jan, 1 1970)|
|X-TOM-NONCE||A random string that must be different between each request|
|X-TOM-API-HASH||The hash string that is used to validate the request|
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 )
$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(
$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.